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The  Apple  IIGS®  is  a  new  kind  of  computer.  It  offers  precise  color 
graphics,  sophisticated  sound  hardware,  a  large  memory  capacity, 
and  an  extensive  toolbox  of  programming  routines — giving  you 
programming  resources  without  precedent  among  personal 
computers.  The  Programmer's  Introduction  to  the  Apple  IIGS  gets 
you  started  writing  programs  that  take  advantage  of  these  unique 
features. 

You  needn't  be  an  expert  programmer  to  benefit  from  this  book, 
but  we  do  assume  that  you  know  some  fundamentals.  Your 
background  will  most  likely  determine  your  approach. 

□  If  you  are  familiar  with  programming  other  Apple®  II 
computers,  and  wondering  how  different  Apple  IIGS 
programming  might  be... 

□  If  you  are  familiar  with  programming  the  Macintosh® 
computer,  and  wondering  how  similar  Apple  IIGS  programming 
might  be... 

n  If  you  are  familiar  with  programming  other  computers,  and 
wondering  how  rewarding  Apple  IIGS  programming  might  be... 

D  If  you  are  familiar  with  using  the  Apple  IIGS,  and  wondering 
how  much  fun  Apple  IIGS  programming  might  be... 

...this  book  will  help  get  you  started.  It  can't  be  a  complete 
programming  course,  but  it  does  cover  the  major  features  that  set 
the  Apple  IIGS  apart  and  make  it  an  exciting  machine  to  write 
programs  for. 


XIII 


You  should  be  familiar  with  the  Apple  IIGS,  at  least  from  a  user's 
perspective,  before  you  start  this  book.  In  particular,  you  should 
understand  how  to  start  the  system  and  how  to  use  the  keyboard, 
mouse,  and  disk  drives. 

We  don't  teach  you  any  programming  languages  here.  The  books 
listed  in  the  next  section  under  "Roadmap  to  the  Apple  IIGS 
Technical  Manuals"  can  help  you  with  C  and  65816  assembly 
language.  The  other  Apple  IIGS  technical  manuals  cover 
individual  topics  in  far  greater  detail  than  we  can  here;  please 
consult  them  as  needed. 

♦  Toolbox  manual:  It  is  not  possible  to  write  the  kind  of  program 
described  here  without  the  aid  of  the  Apple  IIGS  Toolbox 
Reference.  We  give  lots  of  examples  and  general  call 
descriptions  in  this  book,  but  you'll  need  both  volumes  of  the 
Toolbox  Reference  if  you  want  to  write  your  own  applications. 


Roadmap  to  the  Apple  IIGS  technical 
manuals 

The  Apple  IIGS  personal  computer  has  many  advanced  features, 
making  it  more  complex  than  earlier  models  of  the  Apple  II.  To 
describe  it  fully,  Apple  has  produced  a  suite  of  technical  manuals. 
Depending  on  the  way  you  intend  to  use  the  Apple  IIGS,  you  may 
need  to  refer  to  a  select  few  of  the  manuals,  or  you  may  need  to 
refer  to  most  of  them. 

The  technical  manuals  are  listed  in  Table  P-l.  Figure  P-l  is  a 
diagram  showing  the  relationships  among  the  different  manuals. 


xiv  Preface;  Introduction  to  the  Programmer's  Introduction 


To  start  finding  out    _ 
about  the  Apple  II GS 


To  learn  how 


the  Apple  1 1  GS  works 

To  start  learning  to  _ 
program  the  Apple  I 


GS 


To  use  the  toolbox 


To  use  the  development 
environment 


To  operate  on  files 


To  program  in  C 


To  program  in  

assembly  language 


Technical  Introduction 
to  the  Apple  IIgs 


Apple  IIGS 
Hardware 
Reference 


Apple  IIGS 

Firmware 

Reference 


Programmer's 
Introduction 
to  the  Apple  IIgs 


Vol.  1 


Vol.2 


Apple  IIGS 
Toolbox  Reference 


Apple  IIGS  Programmer's 
Workshop  Reference 


Apple  IIGS 
ProDOS  16 
Reference 


ProDOS  8  Technical 
Reference  Manual 


Apple  IIGS  Programmer's 
Workshop  C  Reference 

Apple  IIGS  Programmer's  Workshop 
C  Toolbox  Quick  Reference 


Apple  IIGS  Programmer's  Workshop 
Assembler  Reference 

Apple  IIGS  Programmer's  Workshop 
Assembler  Toolbox  Quick  Reference 


Figure  P-l 

Roadmap  to  the  Apple  IIgs  technical  manuals 


Roadmap  to  the  Apple  IIgs  technical  manuals 


xv 


Table  P-l 

The  Apple  lies  technical  manuals 


Title 


Subject 


Technical  Introduction  to  the  Apple  IIGS 
Apple  IIGS  Hardware  Reference 
Apple  IIGS  Firmware  Reference 
Programmer's  Introduction  to  the  Apple  IIGS 
Apple  IIGS  Toolbox  Reference,  Volume  1 

Apple  IIGS  Toolbox  Reference,  Volume  2 

Apple  lies  Programmer's  Workshop  Reference 

Apple  IIGS  Programmer's  Workshop  Assembler  Reference 

Apple  IIGS  Programmer's  Workshop  C  Reference 

ProDOS  8  Technical  Reference  Manual 

Apple  IIGS  ProDOS  16  Reference 

Human  Interface  Guidelines:  The  Apple  Desktop  Interface 

Apple  Numerics  Manual 


What  the  Apple  IIGS  is 

Machine  internals — hardware 

Machine  internals — firmware 

Concepts  and  a  sample  program 

How  the  tools  work  and  some  toolbox 
specifications 

More  toolbox  specifications 

The  development  environment 

Using  the  APW  Assembler 

Using  C  on  the  Apple  IIGS 
Standard  Apple  II  operating  system 
Apple  IIGS  operating  system  and  loader 
Guidelines  for  the  desktop  interface 
Numerics  for  all  Apple  computers 


XVI 


Preface:  Introduction  to  the  Programmers  Introduction 


Introductory  manuals 

The  introductory  manuals  are  for  developers,  computer 
enthusiasts,  and  other  Apple  IIGS  owners  who  need  technical 
information.  As  introductory  manuals,  their  purpose  is  to  help  the 
technical  reader  understand  the  features  of  the  Apple  IIGS, 
particularly  the  features  that  are  different  from  other  Apple 
computers. 

■  The  technical  introduction:  The  Technical  Introduction  to  the 
Apple  IIGS  is  the  first  book  in  the  suite  of  technical  manuals 
about  the  Apple  IIGS.  It  describes  all  aspects  of  the  Apple  IIGS, 
including  its  features  and  general  design,  the  program 
environments,  the  toolbox,  and  the  development  environment. 

■  The  programmer's  introduction  (this  book):  When  you  start 
writing  Apple  IIGS  programs,  the  Programmer's  Introduction  to 
the  Apple  IIGS  provides  the  concepts  and  guidelines  you  need. 
It  is  not  a  complete  course  in  programming,  only  a  starting 
point  for  programmers  writing  applications  that  use  the  Apple 
desktop  interface  (with  windows,  menus,  and  the  mouse).  It 
introduces  the  routines  in  the  Apple  IIGS  Toolbox  and  includes 
a  sample  event-driven  program. 


Machine  reference  manuals 

There  are  two  reference  manuals  for  the  machine  itself.  They 
contain  detailed  specifications  for  people  who  want  to  know 
exactly  what's  inside  the  machine. 

■  The  hardware  reference  manual:  The  Apple  IIGS  Hardware 
Reference  is  required  reading  for  hardware  developers  and 
anyone  else  who  wants  to  know  how  the  machine  works. 
Information  for  developers  includes  the  mechanical  and 
electrical  specifications  of  all  connectors,  both  internal  and 
external.  Information  of  general  interest  includes  descriptions 
of  the  internal  hardware  and  how  it  affects  the  machine's 
features. 


Roadmap  to  the  Apple  lies  technical  manuals  xvii 


The  firmware  reference  manual  The  Apple  IIGS  Firmware 
Reference  describes  programs  and  subroutines  stored  in  the 
machine's  read-only  memory  (ROM).  The  Firmware  Reference 
includes  information  about  interrupt  routines  and  low-level  I/O 
subroutines  for  the  serial  ports,  the  disk  port,  and  for  the 
Desktop  Bus  interface,  which  controls  the  keyboard  and  the 
mouse.  The  Firmware  Reference  also  describes  the  Monitor 
program,  a  low-level  programming  and  debugging  aid  for 
assembly-language  programs. 


The  toolbox  manuals 

Like  the  Macintosh,  the  Apple  IIGS  has  a  built-in  toolbox  of 
software  routines.  The  two  volumes  of  the  Apple  IIGS  Toolbox 
Reference  completely  describe  the  calls  and  data  structures  for  all 
tool  sets,  and  also  tell  how  to  write  and  install  your  own  tool  set. 

The  desktop  interface  is  If  you  are  developing  an  application  that  uses  the  desktop 

described  in  Chapter  1 .  interface,  or  if  you  want  to  use  the  Super  Hi-Res  graphics  display, 

you'll  find  the  toolbox  indispensable. 


The  Programmer's  Workshop  manual 

The  Apple  IIGS  Programmer's  Workshop  (APW)  is  the 
development  environment  for  the  Apple  IIGS  computer — a  set  of 
programs  that  enables  developers  to  create  application  programs. 
The  Apple  IIGS  Programmer's  Workshop  Reference  describes  the 
APW  Shell,  Editor,  Linker,  and  utility  programs;  these  are  the  parts 
of  the  workshop  that  all  developers  need,  regardless  of  which 
programming  language  they  use. 

The  APW  reference  manual  includes  a  sample  program  to  show 
how  to  create  an  application.  It  also  describes  object  module 
format,  the  file  format  used  by  all  APW  compilers  to  produce  files 
loadable  by  the  Apple  IIGS  System  Loader. 


Programming-language  manuals 

Apple  currently  provides  a  65C816  assembler  and  a  C  compiler. 
Other  compilers  can  be  used  with  the  workshop,  provided  that 
they  follow  the  standards  defined  in  the  Apple  IIGS  Programmer's 
Workshop  Reference. 
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There  is  a  separate  reference  manual  for  each  programming 
language.  Each  manual  includes  the  specifications  of  the  language 
and  of  the  Apple  IIGS  libraries  for  the  language,  and  describes 
how  to  use  the  assembler  or  compiler  for  that  language.  The 
manuals  for  the  languages  Apple  provides  are  the  Apple  IIGS 
Programmer's  Workshop  Assembler  Reference  and  the  Apple  IIGS 
Programmer's  Workshop  C  Reference. 

♦  Note:  The  Apple  IIGS  Programmer's  Workshop  Reference  and 
the  two  programming-language  manuals  are  available  through 
the  Apple  Programmer's  and  Developer's  Association  (APDA). 


Operating-system  manuals 

There  are  two  operating  systems  that  run  on  the  Apple  IIGS: 
ProDOS®  16  and  ProDOS  8.  Each  operating  system  is  described 
in  its  own  manual:  the  Apple  IIGS  ProDOS  16  Reference  and  the 
ProDOS  8  Technical  Reference  Manual.  ProDOS  16  uses  the  full 
power  of  the  Apple  IIGS.  The  ProDOS  16  manual  describes  its 
features  and  includes  information  about  the  System  Loader,  which 
works  closely  with  ProDOS  16  to  load  program  segments  into 
memory. 

ProDOS  8,  previously  called  ProDOS,  is  the  standard  operating 
system  for  most  Apple  II  computers  with  8-bit  CPUs.  It  also  runs 
on  the  Apple  IIGS,  but  it  cannot  access  certain  advanced  Apple 
IIGS  features. 


All-Apple  manuals 

There  are  two  manuals  that  apply  to  all  Apple  computers:  Human 
Interface  Guidelines:  The  Apple  Desktop  Interface  and  Apple 
Numerics  Manual.  If  you  develop  programs  for  any  Apple 
computer,  you  should  know  about  those  manuals. 
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The  Human  Interface  Guidelines  manual  describes  Apple's 
standards  for  the  desktop  interface  of  any  program  that  runs  on 
Apple  computers.  If  you  are  writing  a  commercial  application  for 
the  Apple  IIGS,  you  should  be  familiar  with  the  contents  of  this 
manual. 

The  Apple  Numerics  Manual  is  the  reference  for  the  Standard 
Apple  Numeric  Environment  (SANE™),  a  full  implementation  of 
the  IEEE  Standard  for  Binary  Floating-Point  Arithmetic  (IEEE  Std 
754-1985).  If  your  application  requires  accurate  or  robust 
arithmetic,  you'll  probably  want  to  use  the  SANE  routines  in  the 
Apple  IIGS. 


How  to  use  this  book 

The  Programmer's  Introduction  is  not  a  tutorial.  Rather  than  ask 
you  to  type  in  line  after  line  of  code,  we've  built  the  book  around 
a  finished  example — a  sample  program  named  HodgePodge. 
HodgePodge  is  a  fully  functioning  framework  of  an  application 
that  demonstrates  most  of  the  programming  concepts  we  present 
in  this  book.  More  than  that,  HodgePodge  is  a  rather 
heterogeneous  collection  of  generally  useful  Apple  IIGS 
routines— hence  its  name.  You  are  invited  to  study,  copy,  or 
incorporate  any  of  those  routines,  wholesale  or  piecemeal, 
unchanged  or  greatly  altered,  into  your  own  programs. 

Start  by  reading  Chapter  1.  It  introduces  the  basic  concepts  of  this 
book— event-driven  programming,  the  desktop  user  interface,  the 
Apple  IIGS  Toolbox,  and  program  segmentation. 

Then  run  HodgePodge  to  see  what  it  does.  At  that  point  you 
should  be  ready  for  Chapter  2,  an  extensively  annotated  set  of 
source  listings  of  the  principal  parts  of  HodgePodge.  The  listings 
give  you  the  big  picture  on  how  event-driven  programs  are 
organized,  demonstrate  how  heavily  desktop  programming  relies 
on  toolbox  calls,  and  function  as  templates  for  you  to  use  in  your 
own  programming.  Complete  source  listings  in  Pascal,  C,  and 
65816  assembly  language,  are  in  Appendixes  E  through  G. 
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Chapters  3  through  8  expand  further  on  the  concepts  of  toolbox 
use,  memory  management,  program  segmentation,  the 
development  environment,  and  specialized  program 
requirements.  These  chapters  include  sample  source  listings  where 
appropriate,  but  they  also  discuss  important  Apple  IIGS  concepts 
not  represented  in  any  of  the  samples.  They  are  overviews 
designed  to  give  you  ideas  to  pursue  in  your  own  programming 
when  aided  by  other  reference  manuals. 

Chapter  9  is  a  brief  wrap-up  that  summarizes  general  program 
design  ideas  and  shows  where  to  go  for  further  help. 

Appendixes  include  hints  on  converting  existing  Macintosh 
applications  to  run  on  the  Apple  IIGS,  and  enhancing  existing 
Apple  II  applications  to  take  full  advantage  of  the  new  Apple  IIGS 
features. 

♦  Note:  Please  don't  feel  that  you  need  to  read  this  book  in  any 
order.  Skipping  around  among  programming  examples, 
explanations,  and  theory  may  be  the  best  way  to  absorb  the 
material  presented  here.  Most  important  of  all,  experiment  on 
the  Apple  IIGS  as  you  go  along.  Use  HodgePodge  or  write  your 
own  examples. 


Terms  and  conventions 

This  book  may  define  certain  terms  in  a  slightly  different  manner 
from  which  you  are  accustomed.  Here  are  two: 

■  Apple  II:  A  general  reference  to  the  Apple  II  family  of 
computers.  It  includes  the  Apple  II,  Apple  II  Plus,  Apple  lie, 
Apple  lie,  and  Apple  IIGS. 

■  standard  Apple  II:  Any  Apple  II  computer  that  is  not  an  Apple 
IIGS.  Because  previous  members  of  the  Apple  II  family  share 
many  characteristics,  it  is  useful  to  distinguish  them  as  a  group 
from  the  Apple  IIGS.  A  standard  Apple  II  may  also  be  called  an 
8-bit  Apple  II,  because  of  the  8-bit  registers  in  its  6502  or  65C02 
microprocessor. 
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Typographic  conventions 

Each  new  term  introduced  in  this  book  is  printed  in  bold  type 
where  it  is  first  defined.  That  lets  you  know  that  the  term  has  not 
been  defined  earlier,  and  also  indicates  that  there  is  an  entry  for 
it  in  the  glossary. 

Assembly-language  labels,  entry  points,  program  and  subroutine 
names,  and  filenames  that  appear  in  text  passages  are  printed  in  a 
special  typeface  (for  example,  DoWItem   and   MENU. PAS).  There 
is  one  exception:  the  names  of  Apple  IIGS  system  software  routines, 
such  as  toolbox  calls  and  operating  system  calls  (for  example, 
NewModalDialog  and  QUIT),  are  printed  in  normal  type. 

♦  Note:  The  source-code  listings  of  the  program  HodgePodge 
follow  a  different,  special  typographic  convention.  See  "Code- 
Listing  Convention"  in  Chapter  2. 


Watch  for  these 

The  following  words  mark  special  messages  to  you: 

♦  Note:  Text  set  off  in  this  manner  presents  sidelights  or 
interesting  points  of  information. 


Important     Text  set  off  In  this  manner-with  the  word  Important-presents 
important  information  or  instructions. 


Warning      Text  set  off  in  this  manner-with  the  word  Warning-indicates 
potential  serious  problems. 
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Chapter   1 


Apple  IIgs  Concepts 


Writing  well-designed  programs  for  the  Apple  IIGS  computer  is 
both  an  adventure  and  a  challenge.  It  may  require  some  changes 
in  the  way  you  approach  programming,  some  changes  that  at  first 
seem  confusing.  But  don't  worry;  there  are  tools  and  resources  to 
help  you  at  every  step,  to  make  the  shift  in  programming  style 
relatively  easy.  And  fast. 

As  you  start,  you'll  want  to  keep  several  key  concepts  in  mind.  This 
chapter  introduces  those  basic  ideas.  We'll  be  building  on  them 
throughout  the  book,  and  showing  examples  of  them  in  action,  in 
the  sample  program  HodgePodge.  They  include 

□  desktop  applications — programs  with  a  user  inteface  based  on 
Apple's  Human  Interface  Guidelines 

□  event-driven  programming— creating  the  fundamental  internal 
structure  of  desktop  applications 

□  the  Apple  IIGS  Toolbox — the  extensive  set  of  programming 
routines  that  make  desktop,  event-driven  programming 
practical 

□  segmentation — techniques  that  allow  your  programs  to  use 
memory  more  efficiently 

a  development — steps  to  follow  in  creating  a  running  program 


A  more  powerful  Apple  II 

The  Apple  IIGS  personal  computer  is  a  new  Apple  II  with  many 
high-performance  features.  Some  of  its  highlights  are 

□  a  more  powerful  microprocessor  with  faster  operation  than 
processors  used  in  standard  Apple  II  computers,  and  with  a 
24-bit  address  bus 

□  256K  memory,  expandable  to  8  megabytes 

□  high-resolution  RGB  video  display  for  Super  Hi-Res  color 
graphics  and  text 

□  multi-voice  digital  sound  synthesizer 

□  detached  keyboard  with  Apple  Desktop  Bus™  connector 

D  built-in  I/O:  clock,  disk  port,  and  serial  ports  with  AppleTalk® 
interface 

□  slots  and  game  I/O  connectors  compatible  with  standard 
Apple  II  computers 
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♦  Note:  If  you  are  not  familiar  with  the  Apple  II  family  of 

computers,  you  may  want  to  refer  to  the  Technical  Introduction 
to  the  Apple  IIGS  or  your  Apple  IIGS  Owner's  Guide  for 
explanations  of  some  of  the  terms  in  this  section. 
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Figure  1-1 

Apple  IIgs  features 


A  16-bit  processor  handles  data  in 
chunks  of  16  bits  at  a  time,  twice 
as  much  data  per  cycle  as  an 
8-bit  processor. 


The  65816  microprocessor 

The  microprocessor  in  the  Apple  IIGS  is  a  65SC816,  a  16-bit 
CMOS  design  based  on  the  6502  processor  used  in  previous 
Apple  II  computers.  Among  the  features  of  the  65816  are 

n  ability  to  emulate  6502  and  65C02  8-bit  microprocessors 

a   l6-bit  accumulator  and  index  registers 


A  more  powerful  Apple 


Stack  and  direct-page  concepts 
are  discussed  further  in  Chapter  6. 


a  relocatable  stack  and  direct  page  (zero  page) 

□  24-bit  internal  address  bus,  giving  a  16-megabyte  memory 
space 


Two  execution  modes 

The  65816  microprocessor  can  operate  in  two  different  modes: 
native  mode,  with  all  of  its  new  features,  and  6502  emulation 
mode,  for  running  programs  written  for  standard  (8-bit)  Apple  II 
computers. 

Applications  written  for  the  Apple  IIGS  use  native  mode  with  the 
accumulator  and  index  registers  16  bits  long.  Also,  the  size  of  the 
stack  and  the  locations  of  the  stack  and  direct  page  within  bank 
$00  are  at  the  discretion  of  the  application. 

Two  clock  speeds 

The  microprocessor  in  the  Apple  IIGS  can  operate  at  either  of  two 
clock  speeds:  the  standard  Apple  II  speed  of  1  MHz,  or  the  faster 
speed  of  2.8  MHz.  When  running  programs  in  RAM  the  Apple  IIGS 
uses  a  few  clock  cycles  for  refreshing  memory,  making  the 
effective  processing  speed  about  2.5  MHz.  System  firmware, 
running  in  ROM,  runs  at  the  full  2.8  MHz. 


The  65816  registers  are  discussed 
in  more  detail  in  the  Apple  Hgs 
Hardware  Reference. 


Transformable  registers 

If  you  are  an  assembly-language  programmer,  note  from  Figure 
1-2  how  the  processor's  registers  change  size  to  accommodate 
mode  changes.  The  accumulator  and  X-  and  Y-index  registers 
change  from  8  bits  to  16  bits  in  going  from  emulation  to  native 
mode.  The  stack  pointer  also  becomes  16  bits  long,  meaning  that 
in  native  mode  the  stack  can  be  anywhere  in  bank  $00;  in 
emulation  mode  it  is  confined  to  page  1  of  bank  $00.  The  direct 
register  is  not  used  in  emulation  mode;  in  native  mode  it  is  the 
base  address  for  all  zero-page  addressing  modes,  meaning  that  in 
native  mode  the  Apple  IIGS  can  have  several  zero  pages  (called 
direct  pages),  located  anywhere  in  bank  $00. 
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Figure  1-2 

Program  registers  in  the  65816  microprocessor 


For  additional  memory  concepts, 
see  Chapter  6  of  this  book.  For 
more  complete  Information,  read 
the  Technical  Introduction  to  the 
Apple  IIGS. 


Expanded  memory 

Thanks  to  the  24-bit  addresses  of  the  65816,  the  Apple  IIGS  can 
access  a  total  memory  space  of  16  megabytes.  Of  this  total,  up  to  8 
megabytes  of  memory  is  available  for  RAM  expansion,  and  one 
megabyte  is  available  for  ROM  expansion.  The  rest  is  not  used. 

The  minimum  memory  configuration  for  the  Apple  IIGS  is  256K 
of  RAM.  Programs  written  for  the  Apple  IIGS — that  is,  programs 
that  run  the  65816  microprocessor  in  native  mode  (thereby 
gaining  the  ability  to  address  more  than  64K  of  memory) — can 
use  up  to  about  176K  of  the  256K.  The  rest  is  reserved  for  displays 
and  for  use  by  the  system  firmware. 

♦  Note:  If  your  application  uses  the  Apple  IIGS  Toolbox — as  this 
book  strongly  recommends — your  application  will  have  less 
than  176K  of  available  space  on  a  256K  machine.  So  if  you  are 
writing  anything  other  than  a  very  small  program,  the  program 
will  probably  require  an  Apple  IIGS  with  a  minimum  of  512K  of 
RAM. 
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For  more  information  on  the 
memory  configuration  of 
standard  Apple  II  computers,  see 
the  Apple  lie  Technical 
Reference  Manualor  Apple  lie 
Technical  Reference  Manual. 


Figure  1-3 

Apple  IIgs  memory  map 

The  basic  256K  of  RAM  memory  is  mapped  as  four  banks  ($00, 
$01,  $E0,  and  $E1)  of  64K  each.  As  Figure  1-3  shows,  portions  of 
those  banks  are  reserved  for  system  use  or  I/O  addresses,  just  as 
in  other  Apple  II  computers. 

The  Apple  IIGS  has  a  special  card  slot  dedicated  to  memory 
expansion.  All  the  RAM  on  an  Apple  IIGS  memory  expansion 
card  is  available  for  Apple  IIGS  application  programs.  Expansion 
memory  is  contiguous:  its  address  space  extends  without  a  break 
through  all  the  RAM  on  the  card.  Expansion  RAM  on  the 
Apple  IIGS  is  not  limited  to  use  as  data  storage;  program  code  can 
run  in  any  part  of  RAM. 


Super  Hi-Res  video  display 

The  Apple  IIGS  gives  you  the  most  sophisticated  high-resolution 
color  display  of  any  member  of  the  Apple  II  family.  Now  your 
applications  can  mix  dazzling  color  and  sharp,  80-column  text  or 
precise  line  drawings  on  the  same  screen.  And  do  it  easily,  with 
the  help  of  built-in  toolbox  routines. 
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Hi-Res,  Double  Hi-Res.  and  other 
standard-Apple  II  video  display 
modes  are  described  In  the 
Apple  He  Technical  Reference 
Manual  and  Apple  lie  Technical 
Reference  Manual. 


In  addition  to  all  the  video  display  modes  of  the  Apple  lie  and 
Apple  lie,  the  Apple  IIGS  has  two  new  Super  Hi-Res  display  modes 
that  look  much  clearer  than  standard  Hi-Res  and  Double  Hi-Res. 
Super  Hi-Res  is  also  easier  to  program  than  Hi-Res  or  Double  Hi- 
Res,  because  it  maps  entire  bytes  onto  the  screen,  instead  of  seven 
bits,  and  because  its  memory  map  is  linear. 

Used  with  an  analog  RGB  video  monitor,  the  Apple  IIGS  displays 
high-quality,  high-resolution  color  graphics.  Table  1-1  lists  the 
specifications  of  the  two  new  graphics  modes. 


Table  1-1 

Super  Hi-Res  graphics 

modes 

Horizontal 
Mode            resolution 

Vertical 
resolution 

Bits  per 
pixel 

Colors 
per  line 

Colors 
on  screen 

Colors 
possible 

320               320 
640               640 

200 
200 

4  bits 
2  bits 

16 
16* 

256 
256* 

4096 
4096 

"Different  pixels  in  640  mode  use  different  subsets  of  the  available  colors. 


Pixel  is  short  for  picfure  element.  A 
pixel  corresponds  to  the  smallest 
dot  you  can  draw  on  the  screen. 


For  more  Information  on  using 
color,  see  'Drawing  to  the 
Screen"  in  Chapter  3. 


Each  dot  on  the  Super  Hi-Res  screen  is  a  pixel.  The  screen  image 
is  either  320  pixels  or  640  pixels  across,  by  200  pixels  down.  In 
memory,  each  pixel  has  either  a  2-bit  (640  mode)  or  a  4-bit  (320 
mode)  value  associated  with  it.  The  pixel  values  select  colors  from 
programmable  color  tables.  A  color  table  consists  of  16  entries, 
and  each  entry  is  a  12-bit  value  specifying  one  of  4096  possible 
colors. 

In  320  mode,  each  pixel  consists  of  four  bits,  so  it  can  select  any 
one  of  the  16  colors  in  a  color  table.  Its  palette  is  all  16  colors  in 
the  color  table.  In  640  mode,  each  pixel  is  only  two  bits,  so  it  can 
select  from  four  colors  only.  However,  the  640-mode  color  table  is 
divided  into  four  mini-palettes  of  four  colors  each,  and  successive 
pixels  select  from  successive  groups  of  four  colors.   Thus,  even 
though  a  given  pixel  in  640  mode  can  be  one  of  only  four  colors, 
different  pixels  in  a  line  can  take  on  any  of  the  colors  in  a  color 
table. 

To  further  increase  the  number  of  colors  available  on  the  display, 
there  can  be  up  to  16  different  color  tables  in  use  at  the  same 
time,  giving  as  many  as  256  different  colors  on  the  screen. 
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Pgjfc  5-9  shows  the  majo' 
components  of  the  sound 
harc'v/o;e. 


ror  inore  information  on  Uslfycj 
sound.,  s&e  the  section,  "Making 
Sounds"  In  Chapter  G.  See  also 
"the  /ippto  ikjs  Hotrtwa'e 
ftcfGroncefo'.  deteils  uboul  I  he 
sound  system  and  Ihe  DOC. 


Digital  sound  synthesizer 

Like  other  computers  in  the  Apple  H  family,  the  Apple  UGS  can 
produce  simple,  single-bit  sounds  such  as  disik.s,  beeps,  and  rones. 

But  it  can  afeq  dp  a  whole  lot  more.  The  Apple  JIGS  has  a  new 
digits  sampling  sound  system  bulk  around  a  special-purpose 
synthesizer  TC  called  the  Digital  Oscillator  Chip,  or  DOC  for 
short.  lining  the  DOC,  the  Apple  11GS  can  produce  15- voice  music 
and  other  complex  sounds  without  tying  up  its  main  processor. 

Tiie  sound  system  eaosisEs  of  the  DOC,  an  audio  amplifier  and 
internal  speaker,  a.  connector  for  an  external  amplifier  and 
speaker,  64  K.  of  independent  RAM  for  storage  of  sound  samples, 
and  a.  custom  IC  called  the  Sound  GLU  (general  logic  unit).  The 
Sound,  GLU  is  the  system  interface  to  (he  DQC,  and  also  controls 
tilt:  volume  of  l.he  old-style  single -bit  outpul. 


I  or  more  information  en  using  rho 
Apple  Desktop  Bus.  sec 
"Com-nuricati-ig:  wi'ii  Flies  and 
Deuces'  in  Chapter  5.  See  also 
the  Apple  ties  Tcnibox  Q&f&r&ncc 
arid  Apple  ISgs  I iardware 
HQfemnca 


Detached  keyboard  with  Apple  Desktop  Bus 

The  new  detached  keyboard  includes  cursor  keys  and  a  numeric 
keypad.  Tire  Apple  Desktop  Rus,  which  supports  the  keyboard  and 
the  Apple  Mouse,  can  also  handle  other  input  devices  such  as. 
joysticks  and  graphics  tablets. 


Expansion  slots  and  built-in  I/O 

Tn  addition  to  tin:  memory  expansion  slot  mentioned  earlier,  tire 
Apple  nc.s  has  seven  I/O  expansion  slots  like  those  an  an  Apple 
tie,  Most  peripheral  cards  designed  for  ihe  Apple  n  Plus  and  the 
Apple  He  work  in  the  Apple  tlGS  slots.  The  Apple  lies  also  has 
game  I/O  connectors  for  joysticks  and  other  game  hardware. 

Like  the  Apple  Ik,  the  Apple  TIGS  has  one  built-in  disk  port  and 
iwo  serial  I/O  ports.  The  built-in  AppleTalk  interface  uses  one  of 
the  serial  ports.  Programs  can  use  either  the  built-in  por(s  or 
peripheral  cards  in  slots  to  pfcrforfr)  input/output  functions. 
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Built-in  I/O  features  are  accessed  as  ihough  they  were  peripheral 
cauls  in  skits,  For  most  of  the  expansion  slots,  [he  user  can 
choose  Con  the  Control  ParieQ  between  using  a  peripheral  card  or 
using  ibe  bunt-in  feature  associated  with  the  slot  Table  1-2  shows 
tilt:  si cl-<:( juivalciiLs  for  the  built-in  features. 

Table   1-2 

Apple*  lies  expansion  sJofs  and  interna l-part  equivalents 

Slat  AvoitoSlB  mf».rno!  italuTff 


1  serial  pnrl  Sprinter) 

2  serial  pirt  £commtmicarjoti.s) 

3  fiO-i;»luriiTt  display  firmware 

4  mOUSC  Support 

5  SirutslPoit  (disk  supptut) 
ft  IHSfe  U*  support 

7  Apple-Talk  sup  pnrl 


Clock-calendar  and  Control  Panel 

The  Apple  LiGS  has  a  built-in  real-time  clock.  The  user  .sets  ihij 

time  and  date  with  the  Contra!  Panel,  a  ROM  based  program  that 
h!m>  configures  expa.ii.ikm  skrts,  serial  jjOrtSi  display  color*,  sound 
volume,  and  pitch,  and  other  options 

All  Control  Panel  sellings,  including  the  clock -calendar  values,  are 
maintained  in  a  special  battery-powered  RAM  that  is  maintained 
even  during  power  (nicrrupjions 


Compatibility  with  standard  Apple  11  computers 

Although  the  Appte  ll&s  is  more  powerful  than  previous  Apple  II 
computers,  it  is  still  a  member  of  the  family.  With  the 
microprocessor  sn  6502  emulation  mode,  and  with  the  ProT>OS  8 
operating  system  active,  nearly  any  ProDOS-8-based.  Apple  II 
application  runs  just  H(Kl  on  the  Apple  IlCS.  Tire  only  noticeable 
differrjhcc  is  a  2.5-iLmes  increase  in  execution  speed — and  even 
that  difference  can  be  eliminated  if  your  software  muse  run  at  the 
6502  clock  speed,  Furthermore,  as  just  noted,  most  peripheral 
cants  designed  for  [he  Apple  N  l-'lij.s  or  Apple  Me  will  function 
identically  in  ihe  Apple  IIGS. 
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ProDOS  16  is  the  Apple  IIGS  disk 
operating  syt em.  It  is 
documented  in  the  Apple  IIGS 
ProDOS  16  Reference,  See  also 
Chapter  6  of  this  book. 


Getting  the  most  out  of  the  Apple  IIGS,  however,  requires 
execution  in  65816  native  mode  under  the  more  advanced 
ProDOS  16  operating  system.  That's  what  this  book  is  about: 
writing  programs  that  take  full  advantage  of  the  computer.  Under 
those  conditions,  existing  standard-Apple  II  applications  cannot 
run  without  at  least  some  modification.  If  you  have  written  a 
standard-Apple  II  application,  see  Appendix  B  for  suggestions  on 
how  to  modify  it  for  native-mode  operation  under  ProDOS  16. 


The  Apple  desktop  interface 

Desktop  applications  are  programs  of  a  particular  style — a  style 
that  presents  an  accessible,  nonthreatening,  and  predictably 
consistent  interface  to  the  user.  If  your  programs  show  these 
qualities,  they  will  be  easier  to  learn  and  more  satisfying  to  use. 

The  concepts  behind  this  style  of  program  constitute  the  Apple 
Human  Interface  Guidelines.  This  section  will  help  you  see  what's 
involved  in  writing  an  application  that  follows  the  guidelines. 

Figure  1-4  shows  some  of  the  common  visual  features  of  a  desktop 
application.  The  interface  is  graphics-based  rather  than  text-based. 
The  screen  itself  represents  the  desktop,  upon  which  documents 
appear  in  movable,  scrollable,  overlapping  windows.  Pull-down 
menus  appear  across  the  top  of  the  desktop.  Icons  instead  of  text 
may  represent  certain  concepts  or  objects.  The  user  can 
manipulate  the  menus,  icons,  windows,  and  window  contents  with  a 
mouse  or  other  pointing  device  as  well  as  with  the  keyboard. 
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Figure  1-4 

The  Apple  IIgs  desktop 

These  visual  features  are  not  the  real  essence  of  a  desktop 
application,  however.  The  true  importance  of  desktop  applications 
lies  in  their  relationship  with  the  user,  as  explained  next. 


Human  Interface  Guidelines 

If  you  are  developing  application  programs  for  the  Apple  IIGS 
computer,  you  are  strongly  encouraged  to  follow  the  principles 
presented  in  Human  Interface  Guidelines:  The  Apple  Desktop 
Interface.  That  manual  describes  the  desktop  interface  through 
which  the  computer  user  communicates  with  the  computer  and 
the  applications  running  on  it.  This  section  briefly  outlines  a  few 
of  the  human  interface  concepts.  The  Apple  Desktop  Interface, 
first  introduced  with  the  Macintosh  computer,  is  designed  to 
appeal  to  a  nontechnical  audience.  Whatever  the  purpose  or 
structure  of  your  application,  it  will  communicate  with  the  user  in 
a  consistent,  standard,  and  nonthreatening  manner  if  it  adheres  to 
the  desktop  interface  standards.  These  are  some  of  the  basic 
principles: 

■  Human  control:  Users  should  feel  that  they  are  controlling  the 
program,  rather  than  the  reverse.  Give  them  clear  alternatives 
to  select  from,  and  act  on  their  selections  consistendy. 


The  Apple  desktop  interface 
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■  Dialog:  There  should  be  a  clear  and  friendly  dialog  between 
human  and  computer.  Make  messages  and  requests  to  the  user 
in  plain  English. 

■  Direct  manipulation  and  feedback:  The  user's  physical  actions 
should  produce  physical  results.  When  a  key  is  pressed,  place 
the  corresponding  letter  on  the  screen.  Use  highlighting, 
animation,  and  dialog  boxes  to  show  users  the  possible  actions 
and  their  consequences. 

■  See-and-point  (instead  of  remember-and-type):  The  user  select 
actions  from  alternatives  presented  on  the  screen.  In  general, 
the  process  is  in  the  order  object  followed  by  verb— that  is 
one  selects  first  the  object  to  be  acted  upon,  and  then  the  ' 
action  to  be  performed. 

■  Exploration:  Give  the  user  permission  to  test  out  the 
possibilities  of  the  program  without  worrying  about  negative 
consequences.  Keep  error  messages  infrequent.  Warn  the  user 
when  risky  situations  are  approached,  but  don't  erect 
unnecessary  barriers. 

■  Graphic  design:  Good  graphic  design  is  a  key  feature  of  the 
guidelines.  Objects  on  the  screen  should  be  simple  and  clear 
and  they  should  have  visual  fidelity  (that  is,  they  should  look' 
like  what  they  represent).  Use  familiar,  concrete  metaphors  to 
represent  aspects  of  the  computer  and  program.  The  desktop  i 
the  primary  metaphor  in  the  Apple  Desktop  Interface. 

i  Avoiding  modes:  A  mode  is  a  portion  of  an  application  that 
the  user  must  explicitly  enter  and  leave,  and  that  restricts  the 
operations  that  can  be  performed  while  the  mode  is  in  effect 
By  restricting  the  user's  options,  modes  reinforce  the  idea  that 
computers  are  unnatural  and  unfriendly.  Use  modes  sparingly. 

i  Device-independence:  Make  your  program  as  hardware- 
independent  as  possible.  Don't  bypass  the  system-provided 
software  tool  sets  and  interfaces— your  program  may  become 
incompatible  with  future  products  and  features. 
Consistency:  As  much  as  possible,  all  your  applications  should 
use  the  same  interface.  Don't  confuse  the  user  with  a  different 
look  for  each  program. 

Evolution:  Consistency  does  not  mean  that  you  are  restricted  to 
using  existing  desktop  features.  New  ideas  are  essential  for  the 
evolution  of  the  Human  Interface  concept.  If  your  application 
has  a  feature  that  is  not  described  in  Human  Interface 
Guidelines,  make  sure  it  cannot  be  confused  with  an  existing 
feature.  It  is  better  to  do  something  completely  different  than 
to  half-agree  with  the  guidelines. 
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Appendix  B  discusses  how  writing 
Apple  IIGS  desktop  applications 
differs  from  programming  for 
standard  Apple  II  computers. 


Appendix  A  discusses  how  writing 
Apple  IIGS  desktop  applications 
differs  from  Macintosh 
programming. 


Why  write  desktop  applications? 

The  biggest  reason  for  programming  desktop  applications  on  the 
Apple  IIGS  is  the  consistent  interface  they  present.  Users  spend 
less  time  learning  and  more  time  using  an  application  if  they 
already  know  their  way  around. 

There  are  some  disadvantages  to  desktop  applications.  Apple  IIGS 
desktop  programs  will  not  run  on  the  Apple  He  and  lie.  Because 
desktop  applications  require  the  use  of  graphics  to  support 
windows  and  multiple  fonts,  the  interface  can  be  slower  than  a 
simpler  text-based  command-line  or  menu  interface.  Also  it  takes 
time  to  learn  the  techniques  of  writing  desktop  applications. 

On  the  other  hand,  experience  with  the  Apple  Macintosh 
computer  has  shown  that  an  interface  that  is  consistent  from  one 
application  to  another  is  extremely  attractive  to  users,  because  it 
dramatically  cuts  down  the  learning  time  for  each  new 
application.  The  Apple  desktop  and  the  Human  Interface 
Guidelines  have  been  refined  over  several  years  of  studies  and 
first-hand  experience  by  Apple  and  independent  developers. 

The  cost  to  you  in  development  time  is  minor  when  you  consider 
the  increase  in  your  product's  appeal  due  to  ease  of  use  and 
compatibility  with  the  Macintosh  interface.  In  addition,  if  you  are 
an  Apple  II  developer  new  to  the  Apple  desktop,  the  techniques 
you  learn  (although  not  the  actual  code,  in  most  instances)  are 
directly  applicable  to  the  Macintosh. 


Event-driven  programming 

In  the  old  days  of  programming,  all  programs  were  executed  in 
batch  mode:  the  entire  program  was  put  on  computer  cards  (or 
worse,  punched  paper  tape)  and  fed  into  the  computer  all  at  once. 
The  computer  executed  the  instructions  in  the  same  sequence 
every  time  the  program  was  run  (any  conditional  branching  was 
controlled  by  data  read  in  with  the  program),  reading  data  and 
writing  out  results  at  specified  points  in  the  program. 

Batch  mode  was  fine  for  "crunching  data",  but  it  wasn't  very  useful 
for  applications  (such  as  word  processing  or  drawing)  that  require 
the  user  to  make  decisions  while  the  program  is  running.  When 
computer  terminals  were  invented,  programmers  began  writing 
programs  that  allowed  users  to  send  commands  to  the  computer 
and  wait  for  responses — interactive  programs  were  born. 


Event-driven  programming 
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Any  interactive  program  is  in  some  sense  event-driven.  That  is, 
the  computer  spends  much  of  its  time  waiting  for  some  user  input 
to  occur,  usually  a  key  press.  Traditional  interactive  programs, 
however,  still  largely  control  the  choices  and  the  sequence  in 
which  operations  are  performed.  The  user,  who  follows  rather 
than  leads,  still  feels  that  the  program  is  in  control. 

With  the  introduction  of  the  Apple  Macintosh  and  Lisa® 
computers,  Apple's  Human  Interface  Guidelines  and  event-driven 
programming  came  into  prominence.  The  basic  principle  of 
event-driven  programming  is  that  there  are  many  choices 
available  at  any  time,  and  that  the  user  controls  the  flow  of  the 
program.  In  a  typical  Apple  IIGS  program,  for  example,  the  user 
can  select  choices  from  a  half-dozen  menus,  open  or  close 
windows,  use  desk  accessories,  resize  or  move  windows,  or  do 
some  sort  of  work  (such  as  word  processing  or  drawing).  With  few 
exceptions,  any  of  these  operations  is  available  at  any  given  time. 

Events  that  cause  a  response  by  the  program  include  key  presses 
and  mouse-button  clicks,  and  might  also  include  use  of  game 
paddles,  insertion  of  a  disk  in  a  disk  drive,  data  coming  over  a 
communication  line,  or  even  events  generated  by  the  program 
itself. 


An  event  is  a  notification  to  the 
application  of  some  occurrence, 
internal  or  external,  to  which  the 
application  may  choose  to 
respond. 


The  main  event  loop 

Although  an  event-driven  program  may  at  first  appear  extremely 
complex,  its  basic  structure  is  actually  quite  simple.  It  spends  most 
of  its  time  waiting  in  a  program  loop  called  the  main  event  loop. 
The  only  thing  the  program  is  waiting  for  is  an  event — any  event. 
When  it  detects  an  event,  it  determines  the  type  of  event,  takes 
whatever  action  is  necessary,  and  returns  to  the  main  event  loop 
to  wait  for  the  next  event. 

Figure  1-5  is  a  conceptual  representation  of  the  flow  of  execution 
in  an  event-driven  program.  For  most  of  the  time,  the  taxi 
(program  execution)  remains  in  the  event  loop,  circulating 
constantly,  and  stopping  at  the  taxi  stand  (the  event  queue)  each 
time  to  see  if  there  is  a  waiting  passenger  (an  event).  The  taxi  takes 
passengers  in  order,  one  at  a  time,  to  their  respective  destinations 
(various  event-handling  subroutines).  The  taxi  waits  out  front  while 
the  event  is  being  handled  (execution  temporarily  leaves  the 
event  loop),  then  proceeds  around  the  loop  once  more  to  pick  up 
another  passenger.  Circulation  continues  until  the  program  ends. 
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Event 
Handler 


Figure  1-5 

The  main  event  loop 

For  a  more  specific  example,  assume  that  the  program  is  a  word 
processor.  From  the  user's  point  of  view,  any  of  a  large  number  of 
operations  are  available,  from  typing  a  character  to  reformatting 
the  entire  document  to  setting  control-panel  options.  The  main 
event  loop,  however,  need  wait  for  only  two  types  of  events: 
mouse-button-down  and  key-down. 


Event  handling 

To  illustrate  how  a  program  handles  an  event,  let's  suppose  that 
the  user  decides  to  select  an  item  in  a  window  titled  CORTLAND 
(see,  for  example,  Figure  1-4)  that  is  open  on  the  screen  but  not 
currently  active.  The  user  moves  the  mouse  to  the  inactive  window 
and  clicks  the  mouse  button.  When  the  program  detects  the  event, 
it  handles  it  like  this: 


Event-driven  programming 
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1.  What  kind  of  event  was  it  (mouse-down,  key-down  and  so 
forth)? 

Mouse-down 

(At  this  point  execution  leaves  the  main  event  loop  to  handle 
the  event.) 

2.  Was  it  in  a  window,  on  the  menu  bar,  or  neither? 
Window 

3.  Was  it  the  active  window  or  an  inactive  window? 
Inactive 

4.  Which  inactive  window? 
CORTLAND 

5.  Make  CORTLAND  the  active  window. 

6.  Return  to  the  main  event  loop. 

Why  return  to  the  main  event  loop  now  instead  of  going  to  a  loop 
that  can  handle  events  that  can  occur  only  within  the  active 
window?  Because  the  user  might  change  his  mind  and  decide  to 
open  a  menu,  select  a  different  window,  or  even  quit  the  program 
If  you  return  to  the  main  event  loop  as  soon  as  possible,  the  user 
retains  the  feeling  of  being  in  control  of  the  program. 

The  structure  of  an  event-driven  program  can  be  fundamentally 
different  from  that  of  other  types  of  applications.  Its  principal 
subroutines  are  organized  by  events  to  handle  ("mouse-down " 
"key-down"),  rather  than  by  the  specific  tasks  the  program  was 
written  to  perform  ("text  entry,"  "drawing").  Chapter  2  illustrates 
this  difference  in  detail. 

The  Apple  IIGS  provides  a  large  number  of  software  tools  that 
make  it  easier  for  you  to  write  an  event-driven  program  The 
Event  Manager  performs  the  bookkeeping  that  makes  your 
program's  main  event  loop  work— it  gathers  events,  determines 
T    ,  •„  types'  and  Places  them  in  order,  for  vour  oroeram  ro 

SSKXT  '  d6SCribed  in  handle-  A  "eta  routine  called  TaskMasLZZ^ Stakes 

care  of  simple  event-handling  such  as  resizing  or  moving  a 
window.  Then  it  passes  the  information  on  to  your  program. 
We'll  look  at  events  in  much  greater  detail  as  we  go  along.  Chapters 
2  through  5  describe  the  sequence  of  tool  calls  and  procedures  that 
an  event-driven  program  must  execute  on  the  Apple  IIGS  and 
Appendixes  E  through  G  present  source  code  for  such  a  program  , 
three  different  programming  languages  (assembly  language,  C,  and 
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Tool  and  tool  set  are 
synonymous. 


The  Apple  IIGS  Toolbox 

Trying  to  write  a  desktop,  event-driven  application  without  the  aid 
of  some  powerful  system  software  could  be  quite  difficult. 
Fortunately,  the  Apple  IIGS  comes  equipped  with  a  software 
toolbox,  which  contains  a  complete  complement  of  tool  sets 
designed  to  make  your  job  easier. 

The  Apple  IIGS  tools  support  the  standard  desktop  interface  and 
provide  you  with  building  blocks  to  help  you  construct  your 
application. 


Pen  size  and  pen  mode  are 
discussed  under  "Drawing  to  the 
Screen,"  in  Chapter  3. 


Manager  is  simply  another  name 
for  tool  set. 


What  is  a  tool  set? 

A  tool  set  in  the  Apple  IIGS  environment  is  a  collection  of 
related  software  routines  that  provides  one  major  capability.  Each 
routine  within  a  tool  set  performs  a  fundamental  operation.  For 
example,  the  QuickDraw  II  tool  set  provides  routines  that  handle 
graphics  on  the  Apple  IIGS.  Within  QuickDraw  II,  SetPenSize  and 
SetPenMode  are  routines  that  set  the  pen  size  and  pen  mode.  A 
routine  may  take  one  or  more  specific  parameters  as  input  and 
yield  one  or  more  values  as  output. 

The  tool  sets,  then,  are  groups  of  related  routines  that  perform 
many  common  tasks  and  are  always  available  for  your 
application's  use.  Taken  together,  the  tool  sets  are  very  similar  to 
the  Macintosh  toolbox.  Many  of  the  capabilities  of  the  Apple  IIGS, 
even  those  not  directly  related  to  desktop  applications,  are  easily 
accessed  through  the  tools.  For  example,  both  the  Memory 
Manager  (which  allocates  all  Apple  IIGS  memory)  and  the  Event 
Manager  (which  controls  event-driven  programs)  are  tool  sets. 


The  Apple  IIgs  Toolbox 
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You  can  even  use  the  Tool 
Locator  to  access  a  tool  set  you 
have  written  yourself.  See  "User 
Tool  Sets"  in  Chapter  8. 


Why  use  tool  sets? 

Making  use  of  tool  sets  allows  you  to  concentrate  on  your 
application's  specific  business  rather  than  on  background  work. 

A  number  of  the  tools  are  in  ROM.  They  are  therefore  available  te 
all  programs  without  using  disk  space.  Additional  tools  are 
available  in  RAM,  but  you  needn't  worry  about  where  a  particular 
tool  set  or  routine  is.  A  tool  set  called  the  Tool  Locator,  which 
enables  tool  sets  and  applications  to  communicate,  takes  care  of 
the  necessary  bookkeeping  functions.  All  you  need  to  know  is  the 
name  of  the  routine  and  how  to  call  it  in  your  programming 
language. 

Tool  sets  insulate  your  program  from  the  details  of  machine 
hardware.  If  the  program  accesses  a  hardware  feature  with  a  tool 
call,  the  program  will  remain  compatible  through  future  versions 
of  the  Apple  IIGS,  even  if  the  hardware  feature  changes. 

The  tools  thus  provide  an  abundance  of  capabilities  at  a 
minimum  cost  in  programming  time  and  memory  space.  Their 
bookkeeping  functions  are  almost  automatic,  the  interface  to  them 
is  simple,  and  the  applications  you  write  will  not  be  rendered 
obsolete  by  future  changes  to  the  hardware. 

♦  Note:  Many  of  the  Apple  IIGS  tool  sets  are  independent  of  the 
operating  system.  They  are  thus  available  for  any  Apple  IIGS 
application,  regardless  of  the  operating  system  it  is  written  for. 

To  get  an  idea  of  the  range  of  capabilities  of  the  Apple  IIGS 
Toolbox,  it's  useful  to  group  the  tool  sets  into  categories.  The 
arrangement  given  in  Figure  1-6  is  arbitrary;  as  you  get  to  know  the 
tools  better,  you  may  prefer  other  groupings. 

Brief  explanations  of  the  tool  sets  within  each  category  follow.  The 
tool  sets  are  described  in  more  detail  in  Chapters  3  through  6. 
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The  five  basic 
tool  sets 


Desktop-interface  tool  sets 


Tool  Locator 


Event  Manager 


Memory  Manager 


Miscellaneous 
Tool  Set 


QuickDraw  II 
QuickDraw  II  Auxiliary 


Scrap  Manager 


Desk  Manager 


List  Manager 


LineEdit  Tool  Set 


Font  Manager 


Menu  Manager 


Dialog  Manager 


Control  Manager 


Window  Manager 


Device-interface 
tool  sets 


Operating-environment 
tool  sets 


Specialized  tool  sets 


Apple  Desktop 
Bus  Tool  Set 


Text  Tool  Set 


Print  Manager 


Standard  File 
Operations  Tool  Set 


Scheduler 


System  Loader 


Integer  Math  Tool  Set 


SANE  Tool  Set 


Sound  Tool  Set 


Note  Synthesizer 


Note  Sequencer 


Figure  1-6 

Apple  IIgs  tool  sets 


The  Apple  IIgs  Toolbox 
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The  five  basic  tool  sets 

The  five  tool  sets  listed  below  provide  the  framework  upon  which 
the  other  tools  can  build.  All  of  these  tool  sets  must  be  used  in 
every  event-driven  application: 

■  Tool  Locators  Handles  all  tool  calls.  This  tool  set  relieves  you 
of  having  to  know  where  in  memory  any  tools  resides;  the  Tool 
Locator  finds  and  passes  execution  to  the  proper  routine  when 
you  make  a  tool  call.  Once  you  start  the  Tool  Locator,  its 
operation  is  automatic. 

■  Memory  Manager:  Allocates  memory  for  use  by  the 
application.  When  your  application  needs  memory,  it  must 
request  it  from  the  Memory  Manager. 

■  Miscellaneous  Tool  Set:  Includes  mostly  system-level  routines 
that  must  be  available  for  other  tool  sets  to  use. 

■  QuickDraw  II:  Controls  the  graphics  environment  and  draws 
basic  graphic  objects  and  text  on  the  screen.  QuickDraw  II 
Auxiliary  is  an  extension  to  QuickDraw  II.  Other  tool  sets  call 
QuickDraw  II  and  QuickDraw  II  Auxiliary  to  draw  such  things  as  I 
windows  and  icons. 

■  Event  Manager:  Receives  events  as  they  happen,  maintains  a 
queue  of  events,  and  passes  events  on  to  the  application. 


The  list  of  tool  sets  needed  to 
support  desk  accessories  Is  given 
in  Table  8-1. 


Desktop-interface  tool  sets 

Tools  in  this  group  support  the  desktop  interface.  You  will  almost 
always  use  the  Window  Manager  and  Menu  Manager  in  desktop 
programs;  you  should  use  the  other  tool  sets  if  your  application 
needs  their  features  (for  example,  you  need  the  Dialog  Manager  if 
your  application  uses  dialog  boxes).  Many  of  these  tools  are  also 
needed  to  support  desk  accessories. 

■  Window  Manager:  Creates  and  updates  windows,  keeps  track  of 
size  changes  and  overlapping. 

■  Control  Manager:  Implements  controls — objects  on  the  screen 
such  as  check  boxes — which  the  user  can  manipulate  with  the 
mouse  to  cause  instant  action  or  to  change  settings. 

■  List  Manager:  Along  with  the  Control  Manager,  handles 
ordering,  display,  and  selection  of  lists  of  selectable  items  in 
windows. 
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Dialog  Manager:  Implements  dialog  boxes,  which  your 
application  should  place  on  the  screen  when  it  needs  more 
information  to  carry  out  a  command. 

LineEdlt  Tool  Set:  Presents  text  on  the  screen  (usually  in  dialog 
boxes),  and  allows  the  user  to  edit  that  text  in  limited  ways. 

Menu  Manager:  Controls  and  maintains  pull-down  menus  and 
the  items  in  the  menus. 

Font  Manager:  Provides  fonts  in  a  variety  of  sizes  and  styles  for 
QuickDraw  II  to  use  when  it  draws  text. 

Scrap  Manager:  Supports  the  desk  scrap,  data  to  be  copied 
from  one  application  to  another  (or  from  one  place  to  another 
within  an  application). 

Desk  Manager:  Enables  applications  to  support  desk 
accessories,  mini-applications  that  can  be  run  at  the  same  time 
as  another  application. 


Device-interface  tool  sets 

Tools  in  this  group  manage  input  and  output  between  the 
computer  and  peripheral  devices. 

■  Print  Manager:  Carries  out  page-setup  and  printing  commands 
from  the  user.  Provides  an  interface  between  the  application 
and  printer  drivers. 

■  Standard  File  Operations  Tool  Set:  Presents  dialog  boxes  to  the 
user  when  a  file  is  to  be  saved  or  opened.  Provides  a 
standardized  interface  between  the  user  and  ProDOS  16. 

■  Apple  Desktop  Bus  Tool  Set:  Provides  access  to  Apple  Desktop 
Bus  commands.  The  Apple  Desktop  Bus  transmits  signals  to 
and  from  the  keyboard,  mouse,  and  other  input  devices. 

■  Text  Tool  Set:  Allows  applications  running  in  native  mode  to 
access  Apple  II  character  device  drivers,  which  require  the 
processor  to  be  in  emulation  mode. 
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Operating-environment  tool  sets 

Tool  sets  in  this  group  control  low-level  hardware  and  software 
functions.  The  Memory  Manager  and  the  Miscellaneous  Tool  Set 
listed  under  "The  Five  Basic  Tool  Sets,"  can  also  be  considered 
part  of  this  group.  Other  members  are: 

■  System  Loader:  Loads  all  program  and  data  segments  into 
memory. 

■  Scheduler:  Allows  more  than  one  program  to  access  system 
resources  that  normally  cannot  be  shared. 


Specialized  tool  sets 

Tool  sets  in  this  group  perform  various  specialized  functions,  as  i 
listed. 


Sound  generation 

These  tools  make  it  easy  to  take  advantage  of  the  advanced  sounc 
capabilities  of  the  Apple  IIGS. 

■  Sound  Tool  Set:  Constitutes  the  sound  hardware's  interface  to 
the  Apple  IIGS  Toolbox,  and  provides  basic  sound 
manipulation  routines. 

■  Note  Synthesizer:  Facilitates  creation  of  musical  notes 
simulating  a  variety  of  instruments. 

■  Note  Sequencer:  Strings  together  notes  from  the  synthesizer 
into  the  sequences,  patterns,  and  phrases  that  make  up  a  tune. 

Mathematical  computation 

These  tools  perform  mathematical  functions  and  calculations. 

■  Integer  Math  Tool  Set:  Provides  mathematical  routines  that 
manipulate  integers,  long  integers,  and  signed  fractional 
numbers.  Also  converts  numbers  to  hexadecimal  and  decimal 
ASCII  strings. 

■  SANE  Tool  Set:  Implements  the  Standard  Apple  Numerics 
Environment,  which  provides  extended-precision  floating-pok 
arithmetic  that  conforms  to  IEEE  standard  754.  Supports 
multiplication  and  division  and  trigonometric  and  other 
transcendental  functions. 
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Load  files  are  programs  in 
machine-executable  format. See 
the  Apple  IGS  Programmer's 
Workshop  Referenced 
Information  on  the  file  format  for 
program  segments. 


See  the  Apple  IIGS  ProDOS  16 
Referenced  complete 
information  on  ProDOS  16  and  the 
System  Loader. 


See  the  Apple  IIGS  Toolbox 
Reference  for  complete 
Information  on  the  Memory 
Manager. 


Program  segmentation 

Another  powerful  feature  available  to  Apple  IIGS  programs  is  that 
they  can  be  segmented,  and  the  segments  can  be  relocatable  and 
dynamic.  A  segmented  program  is  divided  into  chunks  that  can 
be  loaded  into  memory  piecemeal.  A  relocatable  segment  is  a 
piece  of  code  or  data  that  needn't  be  put  at  any  particular 
memory  address  in  order  to  function  correctly.  A  dynamic 
segment  is  one  that  is  not  loaded  until  it  is  needed  during 
program  execution. 

Segmentation  of  executable  programs  (load  files)  gives  two 
principal  advantages:  (1)  your  program  might  fit  into  a  smaller 
memory  space  to  help  it  run  in  small-memory  machines  and 
under  application-switching  programs,  and  (2)  it  might  load  and 
start  to  execute  more  quickly.  Both  advantages  occur  because  less- 
needed  segments  can  be  made  dynamic  and  left  on  disk  until  they 
are  actually  called  into  use.  Furthermore,  on  the  Apple  IIGS 
computer  no  single  block  of  code  can  occupy  more  than  64K 
bytes  of  contiguous  memory.  To  load  a  larger  program  than  that, 
you  must  split  it  up  into  two  or  more  load  segments. 

Making  your  load-file  segments  relocatable  means  that  the 
available  memory  in  the  computer  can  be  allocated  efficiently 
among  multiple  programs  (including  system  software  and  desk 
accessories). 

Segmentation  works  because  the  Apple  IIGS  Memory  Manager  and 
System  Loader  tool  sets,  work  together  with  ProDOS  16,  the  Apple 
IIGS  operating  system,  to  execute,  move,  and  remove  program 
segments  in  a  fashion  that  is  sophisticated  yet  totally  transparent 
to  the  program  user  (and  in  many  cases  to  the  programmer  too). 
The  Memory  Manager  takes  care  of  assigning  each  segment  to  a 
block  of  memory;  the  System  Loader  keeps  track  of  where  in 
memory  the  segment  has  been  loaded,  and  patches  intersegment 
calls  in  each  segment  as  it  is  loaded.  ProDOS  16  controls 
execution  of  the  programs  once  they  are  in  memory. 

Chapter  6  presents  a  more  detailed  discussion  of  load-segment 
structure  and  how  the  Memory  Manager,  System  Loader,  and 
ProDOS  16  interact  to  make  it  all  work. 


Program  segmentation 
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Patching  Is  the  process  of 
modifying  code  once  it  Is  In 
computer  memory. 


Absolute  and  relocatable  segments 

To  make  efficient  use  of  memory  with  segmented  programs,  the  t 
Memory  Manager  and  System  Loader  need  to  be  free  to  place 
code  and  data  segments  where  they  choose. 

Absolute  code  is  computer  code  that  must  be  loaded  at  a  specific 
address  in  memory  and  never  moved.  Many  standard  Apple  II 
programs  contain  absolute  code.  The  programmer  decides  when 
the  program  will  sit  in  memory,  and  designs  all  address 
references  and  subroutine  jumps  accordingly. 

Relocatable  code  is  computer  code  that  contains  relative  and 
symbolic  address  references,  and  so  can  execute  correctly 
wherever  it  is  placed  in  memory.  See  Figure  1-7.  Once  it  is  in 
memory,  relocatable  code  must  be  patched  by  the  loader  so  that 
its  address  operands  contain  the  proper  values. 

For  efficient  memory  use,  it  is  very  important  that  as  many 
segments  as  possible  be  relocatable.  The  Memory  Manager  must 
be  free  to  place  segments  so  they  will  not  conflict  with  each  othe 
and  so  that  contiguous  areas  of  free  memory  are  maximized. 
None  of  your  program's  segments  should  be  absolute. 


Absolute 

segment  can't 

be  loaded; 

another  segment 

occupies 

location  $4000 


Relocatable 
segment 
fits  in  any 

open  space 


$6000  - 


$4000 


$2000  - 


$xxxx 


Figure  1-7 

Absolute  and  relocatable  segments 
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See  Chapter  6  for  more 
information  on  how  static  and 
dynamic  segments  are  loaded. 


Static  and  dynamic  segments 

A  dynamic  segment  is  a  load  segment  that  can  be  loaded  and  run 
automatically  during  program  execution.  The  application  itself 
needn't  do  any  loading — whenever  the  application  calls  a  routine 
that  is  in  a  dynamic  segment,  the  segment  is  automatically  loaded 
and  executed.  Furthermore,  that  dynamic  segment  is  not 
subsequently  unloaded  from  memory  unless  the  application 
permits  it,  and  even  then  only  when  the  memory  is  needed  for 
something  else;  in  most  cases  the  segment  remains  instantly 
available  the  next  time  it  is  called. 

A  segment  that  is  not  dynamic  is  static.  A  static  segment  is 
loaded  at  program  startup,  and  is  not  unloaded  or  moved  during 
execution.  The  main  segment  of  any  program  is  static;  any  other 
segments  may  be  static  or  dynamic.  See  Figure  1-8. 

The  question  of  which  segments  to  make  static  and  which  ones  to 
make  dynamic  is  not  as  easily  answered  as  the  question  of 
absolute  and  relocatable.  At  least  one  segment  in  each  program 
must  be  static;  if  the  program  is  small,  that  single  segment  may 
constitute  the  entire  program.  But  if  the  program  is  large  or  if  it  is 
designed  to  require  little  memory,  many  of  its  segments  may  be 
dynamic. 

Making  as  many  segments  dynamic  as  possible  can  also  decrease 
the  time  required  to  initially  load  and  start  up  a  program.  On  the 
other  hand,  there  may  then  be  momentary  delays  during 
execution,  as  the  dynamic  segments  are  loaded  when  called. 
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Figure  1-8 

Static  and  dynamic  segments 
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An  object  file  is  a  program  that 
has  passed  through  an 
assembler  or  compiler.  It  contains 

machine-language  code. 

Chapter  6  shows  you  how  to 
specify  object  segments  and 
load  segments. 


A  source  file  is  a  program  in  its 
original  text  form,  as  written  by  the 
programmer. 


The  Programmer's  Workshop 

To  help  you  write  application  programs  that  make  the  most  of  the 
new  Apple  IIGS  features,  Apple  has  produced  an  integrated 
development  environment  called  the  Apple  IIGS  Programmer's  I 
Workshop  (APW  for  short). 

APW  helps  you  create  event-driven,  segmented  desktop 
applications  that  access  the  full  power  of  the  Apple  IIGS  Toolbox.  II 
With  APW  you  can  write  modular  source-code  segments  in  a 
variety  of  high-level  and  low-level  programming  languages,  and 
then  combine  them  into  a  single  functioning  program. 

APW's  object  files  and  load  files  follow  a  file  specification  called 
object  module  format  (OMF).  OMF  was  developed,  in  part,  to 
create  a  system  in  which  program  segments  written  in  several 
languages  could  be  combined  and  run  together,  because  they  all 
would  have  one  uniform  object  file  "language".  With  OMF  you 
can  optimi2e  various  routines  by  writing  them  in  different 
languages  and  combining  them  into  a  single  program.  A  routine 
written  for  a  program  in  one  language  can  be  dropped  into 
another  program  in  another  language,  without  modification. 

Figure  1-9  is  a  simplified  picture  of  what  takes  place  from  writing 
to  running  an  application  under  APW. 

1.  A  program  is  first  created  as  a  source  file,  using  a  text  editor 
appropriate  for  the  language(s)  involved.  APW  includes  a  full-  j 
featured,  multi-language  text  editor. 

2.  The  source  file,  in  ASCII  text  form,  is  then  either  compiled  or 
assembled  to  produce  an  object  file.  Directives  in  the  source 
file  control  whether  and  how  the  object  file  is  to  be  segmented. 
A  single  source  file  can  be  compiled  into  more  than  one 
object  file. 

3.  The  object  file  is  converted  by  a  linker  into  a  load  file. 
Directives  in  the  original  source  file,  as  well  as  commands  to 
the  linker,  can  control  segmentation  in  the  load  file.  More  than 
one  object  file  can  be  combined  into  a  single  load  file. 

4.  In  the  final  step  (if  all  goes  well),  the  load  file  runs  correctly  when 
the  loader  places  it  in  memory  and  it  is  executed.  In  the  early 
stages,  of  course,  program  development  usually  involves  at  least! 
some  time  with  a  debugger  such  as  the  Apple  IIGS  Debugger. 
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Steps  In  creating  an  application 

Using  APW  to  design  and  write  segmented  programs  is  covered  in 
Chapter  7.  But  before  we  get  too  deeply  into  the  how  of  Apple 
IIGS  programming,  we'd  like  to  show  you  some  more  of  the  what 
and  why.  The  next  five  chapters  present  an  extensive 
programming  example  and  give  some  additional  background, 
showing  what  Apple  IIGS  programs  can  do  and  why  they  go  about 
it  in  the  ways  they  do. 


The  Programmer's  Workshop 
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Chapter  2 


HodgePodge:    A    Sample 
Event-Driven   Application 


29 


Now  that  you've  had  an  overview  of  the  Apple  IIGS  and 
programming  concepts,  let's  plunge  right  into  an  example. 

This  chapter  explores  a  demonstration  application  developed  by 
Apple,  called  HodgePodge.  HodgePodge  has  a  recommended 
organization  for  event-driven,  desktop  applications  on  the  Apple 
IIGS.  We  walk  you  through  the  program,  presenting  the  code  and 
explaining  it  in  detail  as  we  go  along. 

You  may  wonder  why  we're  dissecting  the  sample  program  so 
soon — after  all,  much  of  its  structure  and  most  of  its  tool  calls  and 
parameters  aren't  explained  until  later  in  the  book.  Our  hope  is 
that,  given  the  general  concepts  already  presented  and  the  exten- 
sive commentary  accompanying  these  listings,  your  quickest  route 
to  understanding  is  to  see  actual  code  from  a  functioning  program. 

On  the  other  hand,  there  is  no  required  reading  order  for  this  11 
book.  If  you  want  to  delve  deeper  into  toolbox  concepts  before 
looking  at  code  samples,  by  all  means  skip  ahead  to  Chapters  3  i 
through  5.  Come  back  to  this  chapter  when  you're  ready. 

Don't  forget  to  look  in  Appendixes  E,  F,  and  G  for  the  complete 
source-code  listings  of  HodgePodge  in  all  three  languages 
(assembly  language,  C,  and  Pascal).  And,  whichever  order  you  j 
read  things  in,  don't  forget  to  try  HodgePodge  in  action  on  your 
Apple  IIGS! 


What  HodgePodge  does 

HodgePodge  is  a  short  application  that  loads  stored  graphic 
images  (picture  files)  from  disk  and  displays  them  in  movable, 
scrollable,  resizeable,  overlapping  windows  on  the  screen.  It  also! 
displays,  in  windows,  text  samples  of  the  various  fonts  available  i 
your  system.  See  Figure  2-1. 

Like  a  proper  desktop  application,  HodgePodge  shows  menus, 
displays  messages  in  dialog  boxes,  supports  desk  accessories, 
stores  and  retrieves  files,  prints  text  and  graphics,  and  even 
provides  an  "About  HodgePodge"  dialog  box  accessible  from  the 
Apple  menu. 

If  you  have  a  copy  of  the  sample  program,  put  it  in  your  computer 
and  run  it  now.  On  the  disk  that  accompanies  this  book,  it's  the   j 
application  named  HP,  in  the  folder  for  any  of  the  three  languages. 
(There  are  three  files  named  HP — one  for  each  language.) 
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Figure  2-1 

HodgePodge  desktop 


Hodgepodge's   menus 


HodgePodge  displays  five  pull-down  menus  from  a  menu  bar  at 
the  top  of  the  screen:  Apple  menu,  File  menu,  Edit  menu,  Windows 
menu,  and  Fonts  menu.  Within  each  menu,  items  that  the  user  may 
select' appear  in  black;  items  that  the  user  may  not  select  are 
dimmed  (gray).  When  the  user  selects  an  item  on  a  menu,  that 
menu's  title  is  highlighted  until  the  selected  task  is  completed. 


New  desk  accessories  are 
described  under  "Supporting 
Other  Desktop  Features"  in 
Chapter  5. 


Apple  menu 

The  Apple  menu  is  a  standard  menu  that  all  desktop  applications 
should  have.  Its  title  is  a  small,  colored  Apple  icon.  The  first  item 
in  the  Apple  menu  is  "About  HodgePodge."  Selecting  it  brings  up 
a  dialog  box  that  explains  a  bit  about  the  progam  and  its  authors. 
"About"  dialog  boxes  are  typical  of  desktop  programs. 

The  Apple  menu  also  lists  the  new  desk  accessories  available  on 
the  user's  system. 


What  HodgePodge  does 
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The  Clipboard  and  the  concepts 
of  cut.  copy,  and  paste  are 
described  under  "Supporting 
Other  Desktop  Features"  in 
Chapter  5. 


File  menu 

IhoJlUlT^V"  "  Standard  mCnU  ^  aH  deskt°P  ^Plications 
should  have.  Here  it  contains  seven  items: 

■  Open:  Opens  a  picture  file  and  displays  it  in  a  window. 

■  Close:  Closes  the  frontmost  or  active  window. 

■  Save  As:  Allows  the  user  to  save  a  picture  window  with  its 
present  filename  or  under  another  name. 

■  Choose  Printer:  Allows  the  user  to  select  a  printer. 

■  Page  Setup:  Lets  the  user  set  certain  parameters  for  printing. 

"  window'^15  ^  C°ntentS  °f  Gither  3  piCtUfe  Window  or  a  font 

■  Quit:  Shuts  down  the  program. 

All  of  the  items  in  the  File  menu  are  standard,  but  their 
implementation  in  some  cases  is  specific  to  HodgePodge. 

Edit  menu 

The  Edit  menu  is  a  standard  menu  that  all  desktop  applications 
should  have.  Here  it  contains  five  items:  PP"cauons 

■  Undo:  Allows  the  user  to  reverse  the  last  action  undertaken 

■  Cut:  Deletes  the  selected  part  of  a  document  and  places  the 
selection  in  the  Clipboard. 

"  Cfipboa^r  3  C°Py  °f  thG  SelGCted  Part  °f  a  docume*  ^  the 

■  Paste:  Copies  the  contents  of  the  Clipboard  into  a  document 

'  SSSS? a  selected  part  of  a  document- without  affec^ 

HodgePodge  itself  does  not  use  the  Edit  menu;  however  the  Edit 
menu  must  be  present  in  case  a  desk  accessor  that  nTed^is 


Windows  menu 

The  Windows  menu  is  nothing  but  a  list  of  HodgePodge's 

thTwind  °Pen  Wind°WS-  ™£  liSC  iS  arran*ed  in  *"  oX  in  which 
One  windows  were  opened.  Selecting  the  name  of  a  window  from 
one  widows  menu  causes  that  window  to  be  brought  in  front  3 
any  other  open  windows  on  the  desktop. 
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Fonts  menu 

With  the  Fonts  menu,  the  user  can  display  a  piece  of  sample  text 
using  any  font  on  the  system,  in  any  size  and  with  any  desired 
styling  variation  (such  as  bold  or  italic).  Selecting  the  first  item  on 
the  menu  brings  up  a  dialog  box  with  which  the  user  selects  the 
font  to  display,  and  then  draws  the  text  in  a  window.  Selecting  the 
second  item  toggles  the  display  of  the  next-opened  font  window 
between  proportionally  spaced  and  monospaced  display. 


Hodgepodge's  picture  windows 

HodgePodge  retrieves,  displays,  and  stores  color  pixel  images  in  a 
particular  type  of  picture  file.  The  user  may  open  a  file,  view  the 
picture,  and  then  save  the  file  again  with  the  same  or  another 
name. 

With  picture  windows,  HodgePodge  demonstrates  how  to  create 
windows  and  how  to  display  images  on  the  screen.  It  also  shows 
an  example  of  file  access  and  demonstrates  color  printing.  Figure 
2-2  is  an  example  of  a  picture  displayed  in  a  window. 


Figure  2-2 

A  HodgePodge  picture  window 


What  HodgePodge  does 
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HodgePodge's  font  windows 

HodgePodge  displays  sample  text  in  windows  on  the  screen.  Tha 
text  may  be  in  any  point  size  and  may  have  any  combination  of 
styling  variations  such  as  bold,  italic,  or  underline.  The  text  may 
be  in  any  font  available  on  the  user's  system.  The  actual  lines  of 
text  that  are  displayed  are  specified  in  HodgePodge;  the  user 
cannot  alter  them. 


, 


Many  different  font  windows,  with  different  sizes  and  styles,  ma; 
be  open  simultaneously.  Unlike  picture  windows,  font  windows  are 
not  opened  or  saved  as  files. 

With  font  windows,  HodgePodge  demonstrates  how  to  create 
windows  and  how  to  draw  text  on  the  screen.  Figure  2-3  is  an 
example  of  a  font  window  display. 


Shaston  8 


Shoston  8 


The  quick  brown  fox  jumps  over  the  lazy  dog. 
She  sells  sea  shells  down  by  the  sea  shore. 
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Figure  2-3 

A  HodgePodge  font  window 


How  to  use  the  sample  program 

The  sample  program  serves  two  purposes.  First,  it  provides  a  real 
framework  within  which  to  describe  how  Apple  IIGS  applications 
operate  and  how  they  should  be  written.  Second,  it  provides  you 
with  source  code  modules  that  you  can  adapt  to  your  own 
purposes  on  your  own  programs.  You  are  encouraged  to  use  and 
modify  any  applicable  parts  of  HodgePodge  for  any  programs 
you  write. 
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Because  you  may  be  writing  programs  in  any  of  various  available 
Apple  IIGS  languages,  we  provide  the  sample  program  in  three 
languages-assembly  language,  C,  and  Pascal.  Complete  source 
code  listings  are  in  Appendixes  E  through  G.  The  parts  of  the 
program  listings  reproduced  in  Chapters  2  through  6  are  in 
Pascal. 

♦  HodgePodge  versions.-  Source  code  and  executable  forms  of 
HodgePodge,  in  all  three  languages,  are  on  the  disk  that 
accompanies  this  book.  Sightly  different  versions  of 
HodgePodge,  with  different  features,  have  been  distributed 
through  other  sources  such  as  APDA.  See  Chapter  9. 


See  Appendix  D  for  a  complete 
listing  of  HodgePodge 
subroutines. 


Organization 

The  source  code  for  HodgePodge  consists  of  many  individual 
subroutines  in  several  separate  files.  Figure  2-4  shows  the  overall 
organization  of  the  principal  routines.  The  main  program  (on  the 
left)  calls  each  of  the  principal  subroutines  (on  the  right)  in 
order,  from  top  to  bottom. 


—         SetUpWindows 


Main  program 


HodgePodge 


T 


Quit 


InitGlobals 


StartUpTools 


—         SetUpDefault 


SetUpMenus 


Main  event  loop 


MainEvent 


i 


1 —       ShutDownTools 


Figure  2-4 

HodgePodge  organization  (simplified) 


How  to  use  the  sample  program 
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Hodgepodge's  main  event  loop 
is  described  under  "Cycle 
Through  the  Main  Event  Loop," 
later  in  this  chapter. 


The  most  general  routines,  versions  of  which  will  probably  appear 
in  every  desktop  program  you  write,  are  more  heavily  shaded: 
HodgePodge,  StartUpTools,  SetUpMenus,  MainEvent,  and 
ShutDownTools.  Most  execution  time  is  spent  in  the  main  event 
loop  (MainEvent)  and  in  the  subroutines  that  it  calls. 

Smaller  versions  of  Figure  2-4,  highlighted  to  show  particular 
subroutines,  accompany  discussions  of  the  principal  parts  of  the 
program.  Another  set  of  subroutine  diagrams,  starting  with 
Figure  2-5,  shows  the  flow  of  execution  within  and  from  the  main 
event  loop. 


Pascal  HodgePodge  was  written 
In  TML  Pascal™  for  APW.  See  the 
Bibliography. 


Code-listing  convention 

The  HodgePodge  source  code  listings  in  this  chapter  and 
Chapters  3  through  6  are  in  Pascal.  In  addition  to  the  standard 
Pascal  syntax  and  notation,  please  note  the  following  conventions: 

a  Toolbox  calls  are  in  boldface. 

□  Reserved  words  (such  as  if  then,  begin,  end,  goto)  are  in  italics. 

n  Names  of  functions,  procedures,  types,  and  user-defined 
constants  begin  with  capital  letters. 

□  Names  of  variables,  fields  within  records,  and  toolbox-defined 
constants  begin  with  lowercase  letters. 

a  Boolean  values  (such  as  TRUE  and  FALSE)  are  all  capital 
letters. 


HodgePodge  — I 


HodgePodge  at  a  glance: 
the  main  program 

Briefly,  HodgePodge  (and  any  event-driven  application)  follows 
this  sequence  of  operations  when  it  executes: 

1.  It  starts  up: 

□  It  initializes  variables  and  data  structures. 
a  It  starts  up  the  tool  sets. 

□  It  sets  up  the  program's  menu  bar. 

2.  It  continually  cycles  through  the  main  event  loop. 

3.  As  necessary,  it  handles  application-specific  events. 

4.  Finally,  it  shuts  down. 
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The  HodgePodge  main  program 
Is  In  the  source  file  HP.PAS. 


Most  of  the  above  tasks  are  carried  out  in  subroutines,  but  they  are 
controlled  by  the  main  program.  It  is  very  short;  this  is  what  the 
Pascal  version  looks  like: 


program  HodgePodge; 

{.) 

{• 

{•} 

begin 

InitGlobals; 

if  StartUpTools   then 
begin 
SetUpDefault; 
SetUpMenus; 
SetUpWindows; 
MainEvent ; 
end; 

ShutDownTools; 

end. 


{begin  HodgePodge...} 

USES  and  other  declarations} 

{Initialize  our  globals,  menus,  etc.} 

{if  all  tool  sets  loaded  OK...} 

{Set  up  print  record} 
{Set  up  menus} 
{Set  up  windows} 
{Use  the  application} 

{Shut  down  IIGS  tool  sets} 
{End  of  HodgePodge} 

Subsequent  sections  lead  you  through  the  principal  subroutines 
called  from  the  main  program.  The  subroutines  cover  the  steps 
common  to  most  applications— setting  up,  handling  events,  and 
shutting  down. 

The  details  of  how  HodgePodge  performs  its  own  specific  tasks, 
such  as  displaying  fonts  or  pictures,  are  mostly  left  for  later 
chapters.  Here  we  are  more  interested  in  how  HodgePodge 
illustrates  the  general  independence  of  form  from  function  in 
event-driven  programs.  That  is,  from  a  general  point  of  view  most 
desktop  applications  look  pretty  much  the  same. 


Step  0.  Set  the  stage 

The  source  code  for  a  typical  desktop  application  begins  with 
statements  that  bring  in  needed  library  files,  sets  up  the  operating 
environment,  and  perhaps  defines  some  data  structures.  Many  of 
these  statements  control  what  happens  when  the  program  is 
assembled  or  compiled,  rather  than  when  it  executes. 


Step  0.  Set  the  stage 


37 


□   For  assembly-language  programs,  this  category  includes  such 
tasks  as  selecting  long  or  short  registers,  loading  macro 
libraries,  and.  initializing  various  toolbox  data  structures  with 
using  directives, 

D  For  higher-level  programming  language,  ihis  category  may 
induce  defining  variable  types,  dimensioning  arrays,  and 
loading  library  files. 

Kefer  to  Appendixes  E  ih rough  C  for  details. 

Many  constants  and  da  I  a  structure*  are  predefined  in  (he  interface 
libraries  to  the  Apple  II  gs  Toolbox,  and  tin  is  need  not  be  defined 
wilhin  an  application.  "Ihcy  include  formats  and  field  names  fix 
toolbox  records  and  templates,  and  predefined  constants  fur 
values  such  as  event,  ctxies  and  memory-block  attributes.  We:U 
discuss  thejje  and  other  data  structures  as  we  encounter  them  in 
l  tndgePodge. 


Step  1 .  Start  the  program 

With  the  preliminaries  out  of  tire  way,  let's  look  ai  program 
execution.  To  start  a  desklop  program  off  on  the  riglil  fool,  you  nee; 
to  initialize  any  program -specific  variables  and  data  structures  you! 
are  going  to  use,  start  up  the  tool  sets,  and  set  up  the  system  menu 
bar. 


initialize  variables  and  data  structures 

Where  and  how  you  define  your  data  and  data  structures  depend 
upon  your  program's  purpose,  the  language  you're  using,  and  your 
personal  preference, 

Pascal  HodgePodgc  lias  three  subroutines  called  early  in  program 
execution  to  set  up  initial  values  of  important  components  of  the 
program.  Even  though  two  of  these  routines  are  actually  called 
after  [oo\  startup  (as  Figure  2-4  shows),  all  three  an:  grouped  here 
for  simplicity.  In  general,  your  programs  wilt  do  some 
initialization  before  starting  tools,  and  some  after. 

Unlike  several  of  the  HodgePodge  routines  described  in  this 
chapter,  these  initialization  routines  are  appplication-specific:; 
your  prugram  may  have  very  different  ones. 
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InitGlobals 


SetUpDefault 


SetUpWindows 


InitGlobals  is  in  the  source  file 
GLOBALS.PAS. 


♦  Note:  The  initialization  routines  InitGlobals  and 

SetUpWindows  do  not  appear  in  the  assembly-language  and  C 
versions  of  HodgePodge.  In  those  languages,  variables  can  be 
initialized  as  they  are  defined  in  the  source  file,  rather  than 
during  execution. 

InitGlobals 

InitGlobals  is  the  first  routine  called  from  the  main  program. 
It  initializes  several  variables  and  text  strings  used  later  in  the 
program;  we  will  not  describe  them  individually  here.  It  also 
defines  the  text  strings  that  constitute  HodgePodge's  menus.  (The 
unusual  formatting  of  the  menu  strings  is  explained  under 
"Making  and  Modifying  Menus"  in  Chapter  5.)  In  addition, 
InitGlobals  creates  a  large  colored  Apple  icon  that  is 
displayed  in  the  "About  HodgePodge"  dialog  box  (Figure  4-14). 


procedure  InitGlobals; 

begin 

with   plsWtTemp  do 
begin 
SatRact (dtBoundsRect, 120, 30, 520, 80) 
dtVisible     :=TRUE; 
dtRefCon      :=0; 
dtItemList[0]  :=pointer (0) ; 
dtItemList[l]  :=NIL; 
end; 


{begin  InitGlobals...} 

{template  for  "Please  wait..."  dialog} 

{ — format  defined  by  Dialog  Manager} 

{set  its  size} 

{make  it  visible} 

{no  special  info  here} 

{we'll  insert  this  pointer  later} 

{this  terminates  the  item  list} 

{Now  define  the  text  of  HodgePodge's 
menu  titles  and  items : } 


AppleMenuStr   :=  concat  ('»@\N300X\0'  , 

■ =About  Hodge  Podge . . . \N301\0 ' , 
•=— \N302D\0.'); 

FileMenuStr    :=  concat ('»  File  \N400\0', 

'  =Open .  .  .  \N401*Oo\0 '  , 
•==Close\N255D\0\ 

•  =Save  As .  .  .  \N403D\0 '  , 
>==-\N404D\0\ 

•=Choose  Printer.  .  .\N405\0', 
'=Page  Setup.  .  .\N406D\0' , 

•  =Print .  .  .  \N407 *PpD\0 ' , 
\N408D\0\ 

'  =Quit\N409*Qq\0 .  ' )  ; 
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EditMenuStr 


WindowMenuStr 


FontMenuStr 


concat  ('>>   Edit   \N500D\0', 
'==Undo\N250*Zz\0', 
'=—  \N501D\0', 
'==Cut\N251*Xx\0', 
'==Copy\N252*Cc\0', 
'==Paste\N253*Vv\0 ■ , 
'==Clear\N254\0.  ■ )  ; 

concat ('>>   Window   \N600D\01, 

'==  No  Windows  Allocated\N601D\0 . ' ) ; 

concat  ('>>   Fonts   \N700\0', 

'==Display  Font . . . \N701*Ff \0 ' , 

'==Display  Font  as  Mono-spaced\N702*Mm\0. ' ) 


lastWindow 
noWindStr 
monoStr 
proStr 


=  NIL; 


'==No  Windows  Allocated\N601D\0 . ' , 
'==Display  Font  as  Mono-spaced'; 
'==Display  Font  as  Proportional1; 
isMonoFont  :=  FALSE; 


with   desiredFont  do 
begin 
famNum  :=  $FFFE 
font Style   :=  0 
fontSize    :=  8 
end; 
wlndex  :=  0; 


SetRect (Applelcon.boundsRect, 0, 0, 64, 34) 
HPStuffHex (@AppleIcon.data [1] , 

'00000000000000000000000000000000') 
HPStuffHex (@AppleIcon. data [2] , 

' OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO ' ) 
{.} 

{■ 
{■ 
{■} 


{Now  initialize  other  variables, 
records  &  strings:) 

(window  pointer) 


{item  for  Windows  menu) 
{Item  for  Fonts  menu) 
{Item  for  Fonts  menu) 
{start  fonts  as  proportional) 


{set  default  font  characteristics:} 
{family  number} 
{plain  text} 
{8  pt.} 

{Wlndex  is  the  number  of  open  windows} 

{Last,  define  the  colored  Apple  icon 
to  appear  in  the  "About..."  box : } 

{size  of  icon} 

{HPStuffHex  puts  pixel  values  in  array} 


define  each  pixel  of  the} 
icon (see  Appendix  G) } 
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HPStuffHex(@AppleIcon.data[33] , 

■ OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO ' )  ; 

HPStuf f Hex (SApplelcon . data [ 34 ] , 

■00000OO0OO0O0O0OO0OO00O00O000OO0') ; 


end; 


{End  of   InitGlobals} 


SetUpDefault  Is  in  the  source  file 
PRINT.PAS. 


1 


procedure  SetUpDefault  ; 


begin 

printHndl 


SetUpDefault 

SetUpDefault  creates  a  default  print  record.    (PrRecHdl  is  a 
handle-type,  that  references  a  Print  Manager  print  record.) 
SetUpDefault  must  be  called  after  tool  startup  because  it  makes 
Memory  Manager  and  Print  Manager  calls. 

{begin  SetUpDefault...} 


PrRecHdl (NewHandla (140, 
myMemorylD, 
attrNoCros  s+attrLocked, 

Ptr  (0) )  >  ; 
PrDefault (printHndl) ; 


end; 


{allocate  memory  for  print  record} 

{with  our  ID} 

{and  these  attributes} 

{no  location  restriction} 

{fill  record  with  default  values} 

{end  of  SetUpDefault} 


SetUpWIndows  is  in  the  source  file 
WINDOW. PAS. 


SetUpWindows 

SetUpWindows  sets  initial  window  size  and  position  on  the 
screen.  It  is  called  after  tool  startup,  although  in  this  particular 
case  it  could  just  as  easily  have  been  part  of  InitGlobals. 


procedure   SetUpWindows  ; 

begin 

wXoffset  :=  20; 

wYoffset  :=  12; 
SatRect(iSizPos,10,20,350,80); 

end; 


{begin  SetUpWindows...} 


{set  initial  window  position} 
{from  top  left  corner  of  screen} 
{the  window's  port  rectangle} 
{End  of  SetUpWindows} 


Step  1 .  Start  the  program 
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-    StartUpTools 


StartUpTools  is  in  the  source  file 
HP.PAS. 


Start  up  the  tool  sets 

Proper  initiali2ation,  especially  for  the  Apple  IIGS  Toolbox,  is  1 
critical  for  successfully  running  an  application.  For  that  reason! 
you  are  urged  to  simply  adopt  the  following  code  for  your  owij 
programs.  It  works. 

In  HodgePodge,  tool  startup  is  in  the  subroutine  StartUpTool 
called  from  the  main  program  right  after  InitGlobals.  The 
steps  are  shown  here  in  the  order  in  which  they  are  executed  i 
HodgePodge.  Although  that  is  not  always  the  precise  order  in 
which  they  must  appear  in  your  own  source  code,  tool  startup 
order  is  in  general  very  important.  If  you  change  the  order 
without  knowing  exactly  what  you  are  doing,  your  program  may 
crash. 

The  tool  startup  subroutine  peforms  three  essential  tasks: 

1.  It  loads  the  absolutely  necessary  tool  sets — the  Tool  Locator,! 
the  Memory  Manager,  the  Miscellaneous  Tool  Set,  QuickDraw 
II,  and  the  Event  Manager. 

2.  Using  a  tool  table  and  a  single  LoadTools  call,  it  loads  all  the 
other  tools  HodgePodge  will  need. 

3.  It  starts  up  those  just-loaded  tools,  in  proper  order. 

♦  Note:  Many  of  the  startup  calls  shown  below  require  inputs  or 
return  results.  Look  at  the  discussions  of  individual  tool  sets  i 
Chapters  3  through  5  for  more  information;  see  the  Apple  IIG 
Toolbox  Reference  for  complete  explanations. 

StartUpTools  begins  by  starting  up  the  five  basic  tool  sets.  It 
also  reserves  some  memory  space  (direct-page  space)  needed  b| 
several  of  the  tool  sets. 


function   StartUpTools  :  Boolean; 


const   TotalDP  =  $B00 

DPForQuickDraw  =  $000 

DPForEventMgr  =  $300 

DPForCtlMgr  =  $400 

DPForLineEdit  =  $500 

DPForMenuMgr  =  $600 

DPForStdFile  =  $700 

DPForFontMgr  =  $800 

DPForPrintMgr  =  $900 


var    toolRec    :   ToolTable; 
paramBlock  :   FileRec; 


{begin  StartUpTools...} 

{11  pages  total  direct-page  space} 
{offset  to  QuickDraw  direct  pages} 
{offset  to  Event  Mgr  direct  page} 
{offset  to  Control  Mgr  direct  page} 
{offset  to  LineEdit  direct  page} 
{offset  to  Menu  Mgr  direct  page} 
{offset  to  Std.  File  direct  page} 
{offset  to  Font  Mgr  direct  page} 
{offset  to  Print  Mgr  direct  pages} 

{Tool  Locator  record-type}      ' 
{ProDOS  16  parameter  block} 
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baseDP 
label      1; 


Integer; 


begin 

Start Uptools : =TRUE; 
TLStartUp; 
CheckToolError  ($1)  ; 


myMemorylD 


MMStartUp; 


MTStartUp; 

CheckToolError ($2) ; 

toolsZeroPage  := 

NewHandle (TotalDP , 
myMemorylD, 
att  rBank+att  rFixed+ 
attrLocked+attrPage, 
Ptr(O)); 

CheckToolError ($3) ; 


baseDP  :=  LoWord (toolsZeroPage'')  ; 

QDStartOp 

(BaseDP+DPForQuickDraw, 
ScreenMode , 
MaxScan, 
myMemorylD) ; 
CheckToolError  ($4) ; 

EMStartUp 

(BaseDP+DPForEventMgr, 

20, 

0, 

MaxX, 

0, 

200, 

myMemorylD) ; 
CheckToolError ($5) ; 


(start  address  of  direct  pages} 
(label  used  for  disk-mount  loop} 


(Start  by  assuming  all  will  go  well} 
(start  up  Tool  Locator} 
(check  for  error} 

(Start  up  Memory  Manager:  it  returns 
a  User  ID  for  HodgePodge  to  use} 
(Start  up  Misc  Tools} 
(check  for  error} 

(The  tools  need  direct-page  space:} 
(allocate  11  pages,  supplying...} 
{...HodgePodge'  s  User  ID...} 

{...these  memory-block  attributes...} 
(...and  make  it  in  bank  $00} 
(check  for  error} 

{get  the  2-byte  address  of  the  space} 


(address  of  QuickDraw's  3  dir.  pages} 

(640  mode} 

{max   size  of   scan   line} 

(HodgePodge's   User  ID} 

{check  for  error} 


{address   of  Event  Mgr's   direct   page} 

(event  queue   size} 

{X  min  clamp} 

(X  max  clamp} 

(Y  min  clamp} 

(Y  max  clamp} 

(HodgePodge's   User  ID} 

(check  for  error} 


Next,  StartUpTools  loads  all  RAM-based  tools  and  RAM 
patches  to  ROM-based  tools  at  once,  with  the  LoadTools  call.  It 
first  puts  a  simple  message  on  the  screen  to  notify  the  user  that  it 
is  busy;  then  it  constructs  the  tool  table  (the  list  of  all  tools  to 
load);  and  then  it  loads  them. 


sveTo(20,20) ; 
SatBackColor (0) ; 
SetForeColor  (15) 


(Move  Pen  where  we  want   it} 
(Background  color  =  black} 
(Foreground  color  =  white} 
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DrawString ( ' One  Moment  Please . . . ' ) 
ShowCursor; 


toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 
toolRec 


.numTools 
.tools [1 
.tools  [1 
.tools [2 
.tools  [2 
.tools  [3 
.tools [3 
.tools [4 
.tools [4 
.tools [5 
.tools [5 
.tools [6 
.tools  [6 
.tools [7 
.tools  [7 
•tools [8 
.tools  [8 

•  tools  [9 

•  tools  [9 

•  tools  [10] 
•tools [10] 
•tools [11] 

•  tools  [11] 
•tools [12] 

•  tools  [12] 
•tools [13] 
•tools [13] 

tools [14] 

•  tools  [14] 


:=  14; 

tsNum  :=  4; 
minVersion  :=  0 
tsNum  :=  5; 
minVersion  :=  0 
tsNum  :=  6; 
minVersion  : =  0 
tsNum  :=  14; 
minVersion  :=  0 
tsNum  :=  15; 
minVersion  :=  0 
tsNum  :=  16; 
minVersion  :=  0 
tsNum  :=  18; 
minVersion  :=  0 
tsNum  :=  19; 
minVersion  :=  0 
tsNum  :=  20; 
minVersion  :=  0 
.tsNum  :=  21; 
.minVersion  :=  0 
.tsNum  :=  22 
.  minVersion 
.tsNum  :=  23 
.minVersion 
.tsNum  :=  27 
.minVersion  :=  0 
.tsNum  :=  28 
.minVersion 


paramBlock . pathname  :  =  @  '  * /SYSTEM/TOOLS ' ; 
GET_FILE_INFO (paramBlock) ; 
if  toolErrOO  then 

if  MountBootDisk  =  1  then 

goto   1; 
else 
begin 
StartUpTools  :=  FALSE; 
Exit; 
end; 

LoadTools (toolRec) ; 
CheckToolError($6)  ; 


{Write  the  string  on  screen...} 
{...and  display  the  arrow  cursor} 

{Now  load  RAM  based  tools 
(and  RAM  patches  to  ROM  tools) 
— first,  define  the  contents 
of  the  Tool  table : } 

{14  tool  sets  to  be  loaded} 
{QuickDraw  //} 

{Desk  Manager} 

{Event  Manager} 

{Window  Manager} 

{Menu  Manager} 

{Control  Manager} 

{QuickDraw  Aux} 

{Print  Manager} 

{Line  Edit} 

{Dialog  Manager} 

{Scrap  Manager} 

{Standard  File} 

{Font  Manager} 

{List  Manager} 

{Now  load  the  tools  we've  defined:} 
{here's  the  label} 
{^pathname  of  tool  directory} 
{Look  for  that  directory:} 
{If  it's  not  there...} 
{Ask  user  to  mount  boot  disk...} 
{...If  OK  go  back  and  try  again} 
{But  if  user  cancels...} 

{tool  startup  fails!} 
{...so  quit  this  subroutine) 

{But  if  all  is  OK...} 

{...load  the  tools  named  in  Tool  Table} 

{check  for  error} 
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Note  that,  if  the  disk  with  the  needed  tools  isn't  on  line, 
StartUpTools  calls  the  routine  MountBootDisk,  which 
prompts  the  user  to  remount  the  boot  disk  so  tool  loading  can 
continue.  MountBootDisk  is  described  under  "Error  Handling" 
in  Appendix  D. 

Once  all  the  tool  sets  have  been  loaded,  they  need  to  be  started 
up.  StartUpTools  now  starts  each  one,  in  the  proper  order  and 
with  the  proper  input  parameters  as  needed. 


WindStartOp(myMemorylD) ; 
CheckToolError ($7) ; 


{start  up  Window  Manager} 
{check  for  error) 


RefreshDasktop(NIL) ; 

CtlStartOp 

(myMemorylD, 
BaseDP+DPForCtlMgr)  ; 
CheckToolError ($8) ; 


{redraw  desktop} 

{start  up  Control  Manager} 
{User  ID  for  memory  blocks} 
{address  of  Ctl  Mgr's  direct  page} 
{check  for  error} 


LE Start Up 

(BaseDP+DPForLineEdit , 
myMemorylD) ; 
CheckToolError ($9) ; 


{start  up  Line  Edit} 
{address  of  LineEdit's  direct  page} 
{User  ID  for  memory  blocks} 
{check  for  error} 


DialogStartUp 

(myMemorylD)  ; 
CheckToolError ($A) ; 


{ start  up  Dialog  Manager} 
{User  ID  for  memory  blocks} 
{check  for  error} 


MenuStartUp 

(myMemorylD, 
BaseDP+DPForMenuMgr) ; 
CheckToolError ($B) ; 


{start  up  Menu  Manager} 
{User ID  for  memory  blocks} 
{address  of  Menu  Mgr's  direct  page} 
{check  for  error} 


DeskStartUp; 

CheckToolError  ($C)  ; 


{start  up  Desk  Manager} 
{check  for  error} 


ShowPleaseWait ; 


{Bring  up  a  dialog  box  that  says 
"Please  wait  while  we..." } 


SFStartUp 

(myMemorylD, 
BaseDP+DPForStdFile) ; 
CheckToolError ($D) ; 
SFAllCaps (TRUE) ; 


{start  up  Standard  File} 

{UserlD  for  memory  blocks} 

{address  of  Std  File's  direct  page} 

{check  for  error} 

{Display  file  names  in  all  caps) 


QDAuxStartUp; 

CheckToolError ($E> ; 


{start  up  QuickDraw  Aux} 
{check  for  error} 
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WaitCursor; 

FMStartUp 

(myMemorylD, 

BaseDP+DPForFontMgr)  ; 
CheckToolError ($F) ; 

ListStartOp; 

CheckToolError ($10) ; 

ScrapStartOp; 

CheckToolError ($11) ; 

PMStartUp 

(myMemorylD, 

BaseDP+DPForPrintMgr) ; 
CheckToolError ($12)  ; 

HidePleaseWait ; 
InitCursor; 


end; 


{put  up  watch  cursor, 
now  that  it's  available} 
(start  up  Font  Manager} 
{UserlD  for  memory  blocks} 
(address  of  Font  Mgr's  direct  page} 
(check  for  error} 

(start  up  List  Manager} 
(check  for  error} 

(start  up  Scrap  Manager} 
(check  for  error} 

(start  up  Print  Manager} 
(UserlD  for  memory  blocks} 
(address  of  Print  Mgr's  2  dir.  pages) 
(check  for  error} 

(Remove  the  "Please  wait..."} 
(restore  normal  cursor} 

(End  of  StartUpTools} 


ShowPleaseWait  and 
HidePleaseWait  are  described 
under  "Constructing  Dialog  Boxes 
and  Alerts"  in  Chapter  4. 


This  completes  toolbox  initialization.  The  routine  StartUpTools 
ends  and  returns  control  to  the  main  program  which,  in  addition 
to  calling  the  two  short  initialization  subroutines  SetUpWindows 
and  SetUpDef  ault  (described  earlier  in  this  section),  calls  the 
subroutine  that  sets  up  the  menu  bar.  That  routine,  SetupMenus 
is  described  next. 

♦  ShowPleaseWait:  During  tool  startup,  the  HodgePodge  routine 
ShowPleaseWait  is  called.  It  puts  up  a  dialog  box  that  informs 
the  user  that  the  startup  process  may  take  a  few  seconds  When 
startup  is  done,  HidePleaseWait  removes  the  dialog  box  from 
the  screen.  Keeping  the  user  informed  is  an  important 
component  of  the  Human  Interface  Guidelines. 

♦  Error  handling.-  You  may  have  noted  that,  after  each  tool 
startup  call,  the  HodgePodge  subroutine  CheckToolError  is 
called.  CheckToolError  is  a  very  simple  error  handling 
routine;  it  is  described  under  "Error  Handling"  in  Appendix  D 
It  is  good  practice  to  routinely  check  for  errors  after  making 
tool  calls  that  can  return  them. 
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-    S&IUpMuriuS 


KahipMenus  is  In  "hs  scLjrc;o  \\U.i 
MMJ.PAS. 


Set  up  the  system  menu  bar 

Hie:  routine  that  sets  up  the  menu  bar  when  1  lodge^odge  stfl*#  ap 
is  called  Set:  ypMenus.  5etupMeij.ua  is  called  from  [he  main 
program,  after  start Up Tools  and  the  two  .small  initialization 
routines. 

For  each  menu  in  turn,  SetupMenuH  calls  the  Menu  Manager 
routine  NewMertu,  passing  it  a  pointer  to  a  set  of  diameter  strings 
l.hal.  dc-:firn-i  thcEs  menu  name  and  ihe  items  it  contains.  ("The  menu 
strings  were  defined  in  fhu  routine  iniLGIobals.)  New.Men.ii 
returns  a  handle  to  the  newly  created  menu.  KetupMer.  us  ihen 
calls  InsertMenu,  passing  it  the  menu  handle  and  :i  position 
paramcli-r  (here  defaulted  to  zero.),  to  put  the  menu  into  (he  menu 
bar. 

Final Ly,  SetUpMeuuu  adds  a!  1  desk  accessory  names  10  the  AppU: 
menu  (with  fhe  Desk  Manager  call  FixApplemenuO,  calculates  the 
height  of  the  menu  bar,  and  draws  the  bar. 


ra  r  hei  ght :    T  nteger ; 

begin 

SatMTitleStart (10}; 

InsertMenu  (New Menu  (@JVoiiL  M-e:mS  L  £  f  1 )  )  ,  0 )  ; 
InsertMenu  (NewMenil  ((fWijuJowM^nuSt  1  m  jj  ,  C)  j 
InsertM&im  (HowMonu  { @  Ed  it  Menu  St  r  fl  1  )  ,  (i)  ; 
InsertMenu  (NowMonu  { @ File Menu St r  f  1  1  )  ,  (i)  ; 
InsertMenu  (WawMnnu  (QApplcMrrr-iuSr.  r.  [1  ]  )  ,  0}  ; 

FixAppleMenU  (AnpleMenulD)  ; 


(begin  GetupMenus...] 

{•■  height  oi  menu  £uiiL) 


(Set   aLii^L  position,    from  left  eclge 
ot  menu  ba-r    of  first  morai  title} 
{create  r-nd  tnftatt  Fnnts  Menu) 
{create  and   insert  Windows  Menu} 
f create  and  insert  Edit   Menu) 
{crests  and  insert  File  Men^j 
{crestft  and  insert  Apple  Me:™} 

(Aid  DAs  to  a^ple  menu} 


heiqht    :-   FiKMenuBar; 
D  r awMenuB  a  r ; 


end; 


(Get   sizes   of  menus  J 
{  .  . .    stwi  dtaw   Lire  jiuenu. 
{End   of   SetUpKt'Tiu::) 


jar  3 ) 


Step  1 .  Start  tine  program 
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MainEvent 


TaskMaster  and  GetNextEvent 
are  further  described  under 
"Handling  Events"  in  Chapter  3. 


Step  2.  Cycle  through  the  main  event  loop 

A  desktop  application  spends  most  of  its  time  in  the  main  event 
loop,  waiting  for  an  event  to  handle.  How  an  application  functions 
is  determined  by  what  events  it  chooses  to  handle  and  how  it 
handles  them.  The  event  loops  for  most  programs  are  quite 
similar — it  is  in  the  subroutines  to  which  the  various  events  cause 
branches  that  the  special  personality  of  each  application  lies. 

HodgePodge's  main  event  loop  is  diagrammed  in  Figure  2-5. 
Each  time  through  the  loop,  HodgePodge  checks  whether  it's  time 
to  quit.  If  it  isn't,  HodgePodge  adjusts  menu  items  if  necessary 
and  then  looks  for  the  next  event.  It  does  this  by  calling  the 
Window  Manager  routine  TaskMaster.  Alternatively,  an 
application  could  call  the  Event  manager  routine  GetNextEvent. 

HodgePodge  uses  TaskMaster  because  TaskMaster  automatically 
handles  many  events  for  it.  TaskMaster  itself  calls  GetNextEvent, 
and  takes  care  of  events  that  affect  the  size  and  shape  of  windows, 
such  as  a  mouse  click  in  the  Zoom,  Close,  or  Grow  boxes.  This  is 
not  a  requirement;  your  application  can  ignore  TaskMaster 
entirely  and  do  all  event-handling  itself.  For  example,  you  might 
not  use  TaskMaster  if  you  want  the  application  to  respond  in  an 
atypical  manner. 

If  TaskMaster  can't  completely  handle  an  event,  it  passes  a  task 
code  (described  in  "Handling  Events"  in  Chapter  3)  back  to  the 
application,  and  the  application  must  deal  with  the  event 
specified  by  that  code.  For  example,  if  the  user  selects  a  menu 
item,  TaskMaster  passes  the  information  back  to  the  application, 
which  must  find  out  which  item  was  selected  and  take  the 
appropriate  action. 

When  action  on  an  individual  event  is  finished,  the  application 
(or  TaskMaster)  returns  to  the  main  event  loop  to  wait  for  the  next 
event. 
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back  to 
main  program 


DoMenu 


DoCloseltem 


Figure  2-5 

HodgePodge's  main  event  loop 


MainEvent  is  in  the  source  file 
EVENT.PAS. 


The  loop 

Here  is  the  code  for  HodgePodge's  main  event  loop.  Compare  it 
with  Figure  2-5.  Depending  on  its  features,  your  application  may 
have  an  identical  event  loop,  or  it  may  respond  to  a  different  set 
of  events. 


Step  2.  Cycle  through  the  main  event  loop 
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procedure  MainEvent; 

var  code:      Integer; 

begin 

Event.wmTaskMask  :=  $00001FFF; 
done  :=  FALSE; 

repeat 

CheckFrontW; 

code    :=  TaskMaster ($FFFF,    Event) 


{begin  MainEvent...} 

{the  task  code  (or  event  code) 
returned  by  TaskMaster} 

{pass  all  events  to  TaskMaster} 
{initialize  the  Quit  flag} 


case   code  of 
wlnGoAway: 

DoCloseltem; 
wlnSpecial, 
wlnMenuBar: 
DoMenu 
end; 

until   done; 


end; 


{adjust  menu  items  if  necessary} 
{Call  TaskMaster:  let  it  handle 

all  events;  record  name=Event;  it 

returns  the  task  code} 
{If  the  task  code  represents...} 
{If  a  window  close  box  selected..} 
{...go  to  DoCloseltem} 
{If  an  Edit-menu  item  or  a...} 
{...regular  menu  item  selected..} 
{...go  to  DoMenu} 
{end  of  Case  statement} 

{Stop  when  Done=TRUE} 
{End  of  MainEvent} 

The  different  events  are  specified  by  toolbox-defined  constants 
(such  as  wlnMenuBar)  that  define  Event  Manager  and  TaskMaster 
event  codes.  See  Chapter  3. 

The  main  event  loop  here  is  much  shorter  than  it  would  be  if 
TaskMaster  were  not  used.  Without  TaskMaster,  there  might  have 
been  as  many  as  16  separate  items  in  the  above  case  statement, 
each  with  its  own  subroutine  call. 

♦  Check  front  window:  Each  time  through  the  loop,  before 
checking  for  events,  HodgePodge  determines  which  window  (if 
any)  is  the  frontmost,  and  adjusts  menu  items  accordingly.  For 
example,  if  the  front  window  is  a  font  window,  the  Save  item  on 
the  File  menu  should  be  disabled  because  HodgePodge  does 
not  save  font-window  contents  to  disk.  If  the  front  window  is  a 
desk  accessory  window,  the  Edit  menu  should  be  enabled. 

The  routine  that  does  this  menu  manipulation  is  CheckFrontW. 
It  is  in  the  source  file  EVENT  .  PAS.  See  Appendix  G. 
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Step  3.  Handle  specific  events 

It  may  already  seem  that  the  organization  of  this  program  is  a 
little  different  from  what  you  expected.  So  far,  we've  seen  no 
major  divisions  of  the  code  into  "Picture  Window  Stuff  and 
"Font  Window  Stuff,"  as  you  might  expect  in  a  program  whose 
principal  tasks  are  the  manipulation  of  picture  windows  and  font 
windows. 

Event-driven  programs  have  the  equivalents  to  such  modules,  but 
they  are  chopped  up  and  arranged  in  different  ways.  Elements  of 
them  are  distributed  throughout  the  flow  of  events  in  the  program. 

Therefore  let's  continue  along  the  path  of  execution,  seeing  where 
we  go  when  we  leave  the  main  event  loop  to  handle  the  events 
that  HodgePodge  responds  to.  We'll  mention  each  of  the  types  of 
events  and  point  you  to  where  in  the  book  to  look  for  the  specific 
routine  that  handles  that  event  type. 


Window  closing  is  described 
under  "Window-Related  Events; 
later  In  this  section. 


Window-content  definition 
procedures  are  discussed 
under  "Creating  Windows"  In 
Chapter  4. 


TaskMaster- handled  events 

In  HodgePodge,  TaskMaster  automatically  handles  all  moving, 
resizing,  scrolling,  activating,  updating,  and  redrawing  of  windows. 
It  handles  nearly  all  window  events  automatically.  This  is  a  great 
convenience  (as  you  can  imagine  if  you  are  a  Macintosh 
programmer)  and  it  means  that,  apart  from  closing  a  window, 
there  is  little  for  HodgePodge  to  do  in  terms  of  window 
manipulation. 

In  general,  there  is  one  thing  that  TaskMaster  cannot  do  for  an 
application,  and  that  is  draw  the  contents  of  a  window.  TaskMaster 
cannot  know  what  purpose  the  application  created  the  window  for. 
But,  if  a  window's  contents  can  always  be  described  by  a  routine, 
an  application  can  provide  TaskMaster  with  a  way  to  call  that 
routine  whenever  a  window  is  drawn.  That  routine,  although  part 
of  your  program,  acts  as  a  sort  of  extension  to  TaskMaster,  and  it 
can  do  the  redrawing  of  the  window's  contents.  Such  routines  are 
called  window-content  definition  procedures. 

HodgePodge  uses  this  trick  for  both  picture  windows  and  font 
windows.  Figure  2-6  is  an  extension  to  part  of  the  event-loop 
diagram  of  Figure  2-5,  and  shows  the  window-drawing  routines  that 
are  called  from  within  TaskMaster. 
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TaskMaster       '■— 


Paint 


no 


'  Any  '•■ 

event 

.      9     / 


DispFontWindow 


yes 


Figure  2-6 

HodgePodge  routines  called  by  TaskMaster 

♦  Note:  Don't  get  the  impression  from  Figure  2-6  that  drawing 
window  contents  is  all  that  TaskMaster  does.  TaskMaster  does 
many  more  things,  as  already  discussed,  but  Paint  and 
DispFontWindow  are  the  only  HodgePodge  routines  that 
TaskMaster  calls. 


Paint  is  in  the  source  file 
PAINT.PAS. 


Picture  window  contents 

When  a  picture  window's  contents  need  to  be  drawn  or  redrawn, 
TaskMaster  calls  the  definition  procedure  Paint,  which  sets  up  1 
the  proper  parameters  and  then  calls  the  routine  Paintlt  to  do 
the  actual  drawing.  Paintlt  is  described  under  "Drawing  to  the 
Screen  (and  elsewhere)"  in  Chapter  3.  Paint  looks  like  this: 


procedure   Paint; 

var  tmpPort     :  GrafPortPtr; 

myDataHandle :  WindDataH; 

begin 

tmpPort  :=  GatPort; 

myDataHandle   : =  WindDataH ( 

GetWRefCon (tmpPort) ) 

Paintlt (myDataHandle* A .pict)  ; 

end; 


{begin  Paint...} 

{pointer  to  a  grafPort} 
{handle  to  a  window-data  record 
— defined  in  GLOBALS . PAS } 

{get  a  pointer  to  current  port} 
{Get  a  handle  to  the  window-data...} 
{...record  for  the  current  port} 
{Using  the  picture  pointer  in  the...} 
{...record,  call  the  routine  that 
draws  picture-window  contents} 
{end  of  Paint} 
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Note  that  Paint  (and  Paint  It  too,  as  you  will  see)  is  completely 
unconcerned  about  where  on  the  screen  the  window  to  be  drawn 
appears,  what  other  windows  may  or  may  not  be  in  front  of  it,  and 
even  how  big  the  window  is  or  what  part  of  the  picture  is  being 
displayed.  All  these  details  are  taken  care  of  by  the  toolbox! 


DispFontWIndow  is  In  the  source 
file  FONT.PAS. 


Font  window  contents 

When  a  font  window's  contents  need  to  be  drawn  or  redrawn, 
TaskMaster  calls  the  definition  procedure  DispFontWindow, 
which  sets  up  the  proper  parameters  and  then  calls  the  routine 
ShowFont  to  do  the  actual  drawing.  ShowFont  is  described  in 
Chapter  3,  under  "Drawing  to  the  Screen."  DispFontWindow 
looks  like  this: 


procedure  DispFontWindow; 

var         tmpPort  :    GrafPortPtr; 

myDataHandle :   WindDataH; 

begin 

tmpPort  :=  GetPort; 

myDataHandle   : =  WindDataH ( 

GetWRefCon (tmpPort) ) ; 

with  myDataHandle A/v   do 
ShowFont (theFont, isMono) ; 


end; 


(begin  DispFontWindow...} 

(pointer  to  a  GrafPort} 
(handle  to  a  window-data  record 
—defined  in  GLOBALS.PAS} 

(Get  pointer  to  current  port} 
(Get  a  handle  to  the  window-data...} 
(...record  for  the  current  port} 

(Using  font  info  from  the  record..} 
(...call  the  routine  that  draws 
font -window  contents} 
(End  of  DispFontWindow} 


Just  as  in  the  case  of  picture  windows,  DispFontWindow  and 
ShowFont  are  completely  unconcerned  about  where  on  the 
screen  the  window  to  be  drawn  appears,  what  other  windows  may 
or  may  not  be  in  front  of  it,  and  even  how  big  the  window  is  or 
what  part  of  the  font  display  is  to  be  drawn.  The  toolbox  does  it 
all. 
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Menu-related  events 


DoMenu  is  in  the  source  file 
MENU. PAS. 


Each  of  the  subroutines  listed  in  this  section  is  called  as  the  result 
of  a  menu  selection  made  by  the  user.  Thus  there  is  one 
subheading  for  each  HodgePodge  menu  entry.  Figure  2-7  is  an 
extension  to  part  of  Figure  2-5;  it  shows  which  routines  can  be 
called  when  the  main  event  loop  sends  a  menu-related  event  to 
the  routine  DoMenu. 

When  a  menu  item  is  selected  (either  with  the  mouse  or  with  a 
keyboard-equivalent),  TaskMaster  returns  17  (  =  wlnMenuBar— 
see  "Handling  Events"  in  Chapter  3)  as  the  value  of  myEvent, 
which  causes  execution  to  pass  to  the  subroutine  DoMenu. 
TaskMaster  also  sets  the  taskData  field  of  the  extended  task 
event  record  equal  to  the  menu  ID  and  the  ID  of  the  item 
selected,  and  then  passes  control  back  to  HodgePodge  so  it  may 
perform  the  specific  task.  DoMenu  looks  like  this: 


procedure  DoMenu; 

var  menuNum: 

itemNum: 


Integer- 
Integer; 


{begin  DoMenu...} 


begin 

menuNum 
iteiriNum 


:=  HiWord (Event. wmTaskData) ; 
:=  LoWord (Event. wmTaskData) ; 


{get   number  of  menu  and  item} 


case  itemNum  of 

Aboutltem: 

Openltem: 

Closeltem: 

SaveAsItem: 

ChoosePItem: 

PageSetltem: 

Print Item: 

Quitltem: 

Undoltem: 

Cutltem: 

Copyltem: 

Pasteltem: 

Clearltem: 

Fontltem: 

Monoltem: 
otherwise 

DoWindow (itemNum) ; 
end; 


DoAboutltem; 

DoOpenltem; 

DoCloseltem; 

DoSaveltem; 

DoChooserltem; 

DoSetupItem; 

DoPrintltem; 

DoQuitltem; 


DoOpenltem; 
DoSetMono; 


HiliteMenu (FALSE, menuNum) , 


end; 


{bring  up  "About  HodgePodge"  dialog} 

{open  a  picture  window} 

{close  a  window} 

{save  a  picture  file} 

{choose  a  printer} 

{do  page-setup} 

{print  contents  of  a  window} 

{quit  HodgePodge} 


{ignore  special  menu  items} 

{open  a  font  window} 
{set  font  spacing} 

{bring  the  chosen  window  to  front} 
{of  Case  statement} 

{unHighlight  menu  title} 

{End  of  DoMenu} 
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The  menu  ID  variables  (Closeltem,  About  Item,  and  so  forth) 
are  defined  in  the  source  file  GLOBALS  .  PAS. 


Menu  \yesJ< 

event  /'      *1 

-.     9    ./'  • 


DoMenu 


DoWindow 


DoCloseltem 


DoAboutltem 


DoQuitltem 


DoOpenltem 


DoSaveltem 


DoChooseltem 


DoSetupltem 


-        DoPrintltem 


L        DoSetMono 


Figure  2-7 

HodgePodge  routines  that  handle  menu-related  events 

The  various  routines  called  by  DoMenu  are  listed  either  elsewhere 
in  this  book  or  in  Appendix  G.  In  brief,  this  is  what  each  does: 

■  DoAboutltem:  Brings  up  the  "About  HodgePodge"  dialog  box. 
DoAboutltem  is  listed  under  "Constructing  Dialog  Boxes  and 
Alerts"  in  Chapter  4. 

■  DoOpenltem:  Opens  a  font  or  picture  window.  DoOpenltem 
calls  OpenWindow  to  open  the  window,  then  calls  AddToMenu 
to  add  the  window's  name  to  the  Windows  menu.  DoOpenltem 
is  listed  under  "Opening  a  Window:  An  Example"  in  Chapter  4. 
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■  DoCloseltem:  Closes  a  font  or  picture  window,  releases  its 
allocated  memory,  and  adjusts  the  Windows  menu 
DoCloseltem  is  listed  under  "Window-Related  Events  "  later 
in  this  section. 

■  £oSaveItem:  Saves  the  contents  of  a  picture  window  as  a  disk 
tile  DoSaveltem  is  listed  under  "Communicating  With  Files 
and  Devices"  in  Chapter  5. 

■  DoChooserltem:  Brings  up  a  dialog  box  permitting  the  user  to 
choose  a  printing  device.  DoChooserltem  is  listed  under 

Communicating  With  Files  and  Devices"  in  Chapter  5. 

■  DoSetupItem:  Brings  up  a  dialog  box  permitting  the  user  to  set 
page-setup  parameters.  DoSetupItem  is  listed  under 
"Communicating  With  Files  and  Devices"  in  Chapter  5. 

i  DoPrintltem:  Prints  the  contents  of  the  frontmost  window 
DoPnntltem  is  listed  under  "Communicating  With  Files  and 
Devices"  in  Chapter  5. 

'  ^°Qu""em:  ^s^ns  the  value  TRUE  to  the  boolean  variable 
done.  That  causes  temination  of  the  main  event  loop 
DoQuitltem  is  in  the  source  file  MENU .  PAS.  See  Appendix  G| 
DoSetMono:  Toggles  a  flag  that  controls  whether  fonts  are 
displayed  as  monospaced  or  proportional,  and  updates  the 
Fonts  menu  accordingly.  DoSetMono  is  in  the  source  file 
FONT .  PAS.  See  Appendix  G. 

DoWindow:  Brings  the  selected  window  (chosen  from  the 
Windows  menu)  to  the  front.  DoWindow  is  in  the  source  file 
MENU.  PAS.  See  Appendix  G 


set 


Window-related  events 

Closing  is  the  only  window-related  event  that  HodgePodge  must 
respond  to  explicitly.  Figure  2-8  is  an  extension  to  part  ofpigure 
2-5;  it  shows  the  routines  that  can  be  called  when  the  main  event 
loop  encounters  a  window-related  event. 
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.••■'  Close'--.. 

window 
..  event  / 

\   ">  / 


yes 


DoCloseltem 


AdjWind 


DoCloseltem  is  in  the  source  file 
WINDOW. PAS. 


Figure  2-8 

HodgePodge  routines  that  handle  window-related  events 

Closing  is  a  window  event,  but  it  is  also  a  menu  event .  When  the 
user  clicks  in  an  active  window's  close  box,  or  selects  Close  from 
the  File  menu,  TaskMaster  returns  that  information  to 
HodgePodge,  which  in  turn  calls  DoCloseltem.  DoCloseltem  is 
also  called  at  program  shutdown,  to  close  all  windows.  Its  source 
code  looks  like  this: 


procedure  DoCloseltem; 

var         theWindow        :    GrafPortPtr; 
myDataHandle :   WindDataH; 

begin 

theWindow  :=  FrontWindow; 

CloseNDAbyWinPtr (theWindow) ; 
if  isToolError  then 
begin 
AdjWind (theWindow) ; 
myDataHandle  : =  WindDataH ( 

GetWRef Con (theWindow) ) ; 
DisposeHandle (Handle (myDataHandle) ) ; 
ClosaWindow (theWindow) ; 
Dec  (wlndex)  ; 
end; 
end; 


{begin  DoCloseltem...} 

{ptr  to  window  to  be  closed} 
{window-data- record  handle} 


{Get  a  pointer  to  the  front  window} 

{Assume  that  it's  a  desk  ace.  window} 
{If  it  wasn't  an  NDA  window...} 

{Call  AdjWind  to  update  menu} 
{Get  a  handle  to  window's...} 
{...window-data  record} 
{Get  rid  of  the  window-data  record} 
{Get  rid  of  the  window  completely} 
{decrease  number  of  open  windows} 
{end  of  IF  wasn't  an  NDA} 
{end  of  DoCloseltem} 


AdjWind:  DoCloseltem  calls  the  HodgePodge  routine 
AdjWind,  which  removes  the  name  of  the  just-closed  window 
from  the  Windows  menu.  AdjWind  is  described  under  "Making 
and  Modifying  Menus"  in  Chapter  5. 
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ShutDownTools 


ShutDownTools  is  In  the  source  file 
HP. PAS. 


Step  4.  Shut  down  the  program 

When  it's  time  for  your  application  to  quit,  the  following  steps 
ensure  a  graceful  exit: 

1.  Shut  down  all  tool  sets  in  reverse  order  from  the  way  you 
started  them  up. 

2.  Release  any  memory  your  application  requested  from  the 
Memory  Manager. 

3.  Shut  down  the  Memory  Manager  (with  your  application's  User 
ID  as  input). 

4.  Shut  down  the  Tool  Locator. 

5.  In  assembly  language,  use  the  ProDOS  16  QUIT  call  to  leave  tk 
application.  (In  C  and  Pascal,  this  is  taken  care  of  for  you). 

HodgePodge  terminates  when  the  user  selects  Quit  from  the  File 
menu.  The  routine  DoQuitltem  executes,  setting  the  variable  done 
to  TRUE,  which  causes  the  main  event  loop  to  stop.  Execution  passes 
to  the  main  program,  which  calls  ShutDownTools  and  ends. 

ShutDownTools  shuts  down  all  tool  sets,  in  reverse  order  from 
startup.  You  may  be  able  to  use.  this  code  verbatim  in  your 
programs.  It  looks  like  this: 


procedure  ShutDownTools; 
begin 

DeskShutDown; 

if  WindStatua   <>   0    then 
HideAUWindows; 

ListShutDown; 

FMShutDown; 

ScrapShutDown; 

PMShutDown; 

QDAuxShutDown ; 

SFShutDown; 

Menu  Shut  Down ; 

DialogShutDown; 

LEShutDown; 

CtlShutDown; 

WindShutDown ; 

EMShutDown ; 

QDShutDown; 

MTShutDown; 


{begin  ShutDownTools...} 

{shut   down  Desk  Manager} 
{make   sure  Window  Mgr.    active...} 
{close  all  windows — this  may  take 
some  time   if  many  open  windows ! } 
{shut   down  List  Manager} 
{shut  down  Font  Manager} 
{shut  down  Scrap  Manager} 
{shut   down  Print  Manager} 
{shut  down  Quick  Draw  Aux} 
{shut  down  Standard  File} 
{shut   down  Menu  Manager} 
{shut   down  Dialog  Manager} 
{shut   down  Line  Edit} 
{shut   down  Control  Manager} 
{shut   down  Window  Manager} 
{shut   down  Event  Manager} 
{shut   down  QuickDraw  II} 
{shut   down  Misc.    Tool   Set} 
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if  MMStatus  <>   0   then 
begin 
DispoaeHandla (toolsZeroPage)  ; 
MMShutDown (myMemorylD)  ; 
end; 
TLShutDown; 
end; 


{If  Memory  Mgr.    active...} 
{delete  the  direct -page  memory...} 
{...allocated  at   startup} 
{shut   down  Memory  Manager} 

{shut   down  Tool  Locator} 
{End  of  ShutDownTools} 


♦  HideAUWindows:  Note  that  ShutDownTools  calls 

HideAllWindows,  which  simply  closes  all  windows  and 
releases  their  associated  memory.  HideAllWindows  is  in  the 
source  file  WINDOW.  PAS.  See  Appendix  G. 


Conclusion 

This  completes  our  overview  of  the  organization  of  HodgePodge. 
You  can  see  that  it  has  a  structure  almost  independent  of  the  tasks 
it  was  written  to  perform.  That,  of  course,  is  the  intention — if  all 
event-driven  programs  execute  in  a  similar  manner,  they  can 
present  a  uniform  interface  to  the  user.  In  addition,  they  can  be 
extended  easily  to  add  new  features,  and  they  can  remain 
compatible  with  future  revisions  of  system  software. 

The  rest  of  the  book  gives  more  details  on  how  HodgePodge 
actually  performs  its  individual  tasks,  and  gives  some  of  the 
concepts  behind  the  tool  calls  that  HodgePodge,  like  any  event- 
driven  program,  needs  to  make.  Most  discussions  are  general,  but 
HodgePodge  listings  are  included  where  appropriate.  See  Table  2-1. 

Table  2-1 

HodgePodge  routines  described  in  this  book 


Routine 


See  chapter  and  section... 


AddToMenu 

AdjWind 

AskUser 

CheckToolError 

CheckDiskError 

DispFontWindow 

DoAboutltem 


Chap.  5:  "Making  and  Modifying  Menus" 

Chap.  5:  "Making  and  Modifying  Menus" 

Chap.  5:  "Communicating  With  Files..." 

App.  D:  "Error  Handling" 

App.  D:  "Error  handling" 

Chap.  2:  "Handle  Specific  Events" 

Chap.  4:  "Constructing  Dialog  Boxes..." 


Conclusion 
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Table  2-1  (continued) 

HodgePodge  routines  described  in  this  book 

Routine 


See  chapter  and  section... 


DoChooseFont 

DoChooserltem 

DoCloseltem 

DoMenu 

DoPrintltem 

DoSaveltem 

DoSetUpItem 

DoTheOpen 

DrawTopWindow 

HodgePodge 
InitGlobals 

StartUptools 

LoadOne 

MainEventLoop 

MountBootDisk 

OpenWindow 

Paint 

Paintlt 

SaveOne 

SetUpDefault 

SetUpMenus 

SetUpWindows 

ShowFont 

ShutDownTools 


Chap.  3:  "Drawing  to  the  Screen" 

Chap.  5:  "Communicating  With  Files 

Chap.  2:  "Handle  Specific  Events 

Chap.  2:  "Handle  Specific  Events 

Chap.  5:  "Communicating  With  Files..." 

Chap.  5:  "Communicating  With  Files..." 

Chap.  5:  "Communicating  With  Files..." 

Chap.  4:  "Creating  Windows" 

Chap.  5:  "Communicating  With  Files..." 

Chap.  2:  "HodgePodge  at  a  Glance 

Chap.  2:  "Start  the  Program" 

Chap.  2:  "Start  the  Program" 

Chap.  6:  "The  ProDOS  File  System 

Chap.  2:  "Cycle  Through  the  MainEvent 

App.  D:  "Error  Handling" 

Chap.  4:  "Creating  Windows" 

Chap.  2:  "Handle  Specific  Events" 

Chap.  3:  "Drawing  to  the  Screen" 

Chap.  6:  "The  ProDOS  File  System 

Chap.  2:  "Start  the  Program" 

Chap.  2:  "Start  the  Program" 

Chap.  2:  "Start  the  Program" 

Chap.  3:  "Drawing  to  the  Screen" 

Chap.  2:  "Shut  Down  the  Program 
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Chapter  3 


Using  the  Toolbox  (I) 
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The  complete  reference  for  all 
toolbox  calls  is  the  Apple  Hgs 
Toolbox  Reference,  in  two 
volumes. 


In  Chapter  2,  the  sample  program  HodgePodge  showed  an 
example  of  toolbox  use  in  action.  Now  let's  examine  some  of  the 
concepts  behind  the  toolbox  calls  HodgePodge  makes.  Even 

t2t^,Tl    oryuook  like  this  can  only  «et  y°u  started  ^ 

each  tool  set,  the  overall  view  of  what  the  tools  can  do  for  you 
and  the  example  of  how  HodgePodge  integrates  them  should  take 
you  a  long  way  toward  understanding  and  exploiting  their  power. 
The  Apple  IIGS  Toolbox  is  made  up  of  about  30  tool  sets.  Each 
tool  set  is  made  up  of  many  routines.  In  all,  there  are  more  than 
800  toolbox  routines  in  ROM  and  RAM,  covering  a  wide  variety  of 
tasks  from  managing  memory  to  drawing  to  the  screen  to  giving 
ZJ    »Te       ^^  And  don't  ™rv-you  needn't  memorize 

tZ^-l  WT  7  APPIG  HGS  W""*™-  Ju«  the  few  you  learn 
trom  this  book  will  get  you  started. 

s^brorn^^  °f  ^  ?°lbOX  3S  a  V6ry  largS  Ub^y  of  P™"en 
subroutines,  optimized  and  integrated  to  relieve  you  of  a  large 

part  of  your  programming  burden.  They  exist  to  free  you  to 
concentrate  on  the  fundamental,  creative  aspects  of  the  program 
you  want  to  write.  F    s 

In  this  chapter  we  discuss  events  and  how  to  handle  them,  and  the 
basic  process  of  drawing  to  the  Apple  IIGS  screen  by  using 
QuickDraw  II.  Chapters  4  and  5  describe  the  remaining  tool  sets. 
We  11  include  actual  examples  from  HodgePodge  where 
appropriate,  but  otherwise  the  details  of  individual  calls  and  their 
parameters  are  left  for  other  books. 


Starting  up  and  calling  the  tools 

lnvlo7L7rn  iC  h°V°aded  3nd  *****  ^  before  you  can  call 

2    m    ° T'  lso' some  tOGl  sets  cal1  others' so  y°u  ™t 

start  them  up  in  the  proper  order. 


Required  tool  sets 

Apple  IIGS  Toolbox.  Start  them  first,  and  start  them  in  this  order: 
1.  The  Tool  Locator 
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Refer  to  "Set  the  Stage"  in 
Chapter  2  to  see  how  closely 
HodgePodge  follows  this 
sequence. 


HodgePodge's  tool  table  is 
initialized  in  the  routine 
StartUpTools. 

Important 

For  a  list  of  all  current  tool  sets  and 
their  numbers,  see  "User  Tool 
Sets"  in  Chapter  8. 


2,  The  Memory  Manager 

3-  The  Miscellaneous  Tool  Set 

Beyond  these  three,  there  are  two  other  tool  sets  that,  while  not 
absolutely  required  for  the  Apple  IIGS  to  function,  are  nevertheless 
used  in  nearly  every  application.  Start  them  up  in  this  order: 

4.  QuickDraw  II 

5.  The  Event  Manager 


Other  tool  sets 

After  the  required  tool  sets  are  in  place,  you  should  load  and  start 
up  all  other  tool  sets  your  application  might  use. 


Loading 

To  simplify  things,  and  to  ensure  that  the  correct  versions  of  tool 
sets  are  available,  it's  best  to  load  all  of  your  needed  tool  sets  at 
once,  with  the  Tool  Locator's  LoadTools  call.  LoadTools  does  two 
things:  it  loads  RAM-based  tools  into  the  computer  (remember, 
some  tools  are  not  in  ROM),  and  it  checks  the  version  numbers  of 
all  the  specified  tool  sets,  whether  in  ROM  or  RAM.  That  version 
check  is  important  because  some  tool  sets  will  not  function 
without  the  proper  minimum  versions  of  other  tool  sets. 

When  you  make  the  LoadTools  call,  you  pass  it  a  pointer  to  a  tool 
table,  which  lists  the  total  number  of  tool  sets  to  load,  and  the 
number  and  minimum  acceptable  version  of  each  tool  set. 


Make  sure  that  all  the  RAM-based  tools  your  program  needs  are  in 
the  TOOLS  subdirectory  of  the  SYSTEM  directory  on  the  system  disk. 
See  Appendix  C. 


Starting  up 

After  you  have  loaded  the  remaining  tool  sets,  you  must  then  start 
up  each  one.  Each  tool  set  has  its  own  startup  call;  some  calls 
require  or  return  parameters,  others  have  no  inputs  or  outputs. 
Because  some  tool  sets  require  the  presence  of  other  tool  sets  in 
order  to  function,  tool  sets  must  be  started  in  proper  order.  Table 
3-1  gives  the  suggested  startup  order. 


Starting  up  and  calling  the  tools 
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Table 

3-1 

Tool  set  startup  order 

Hex. 

Dec. 

Name 

$01 

1 

Tool  Locator 

$02 

2 

Memory  Manager 

$03 

3 

Miscellaneous  Tool  Set 

$04 

4 

QuickDraw  II 

$06 

6 

Event  Manager 

$0E 

14 

Window  Manager 

$10 

16 

Control  Manager 

$0F 

15 

Menu  Manager 

$14 

20 

LineEdit  Tool  Set 

$15 

21 

Dialog  Manager 

$05 

5 

Desk  Manager 

$17 

23 

Standard  File  Operations  Tool  Set 

$16 

22 

Scrap  Manager 

$1C 

28 

List  Manager 

$13 

19 

Print  Manager 

$1B 

27 

Font  Manager 

You  can  assume  that  tool  sets  not  on  this  list  are  either  started  up 
already,  or  can  be  started  in  any  order. 

♦  HodgePodge:  You  may  have  noticed  that  HodgePodge  doesn't 
follow  this  sequence  exactly  when  it  starts  its  tool  sets. 
Specifically,  it  starts  up  the  Menu  Manager  after  starting  the 
LineEdit  Tool  Set  and  the  Dialog  Manager.  So  in  some 
instances  it  may  be  possible  to  alter  startup  order  slightly,  but  it 
is  safest  just  to  follow  the  order  given  in  Table  3-1. 

In  addition  to  the  dependencies  reflected  in  the  startup  order  for 
tool  sets,  there  are  additional,  complex  dependencies  among  tool 
sets  because  a  routine  in  one  tool  set  may  call  routines  in  other 
tool  sets  (which  may  call  routines  in  still  other  tool  sets,  and  so 
on).  These  dependencies  are  beyond  the  scope  of  this  book;  see 
the  individual  tool  set  and  routine  descriptions  in  the  Apple  IIGS 
Toolbox  Reference. 
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Calling  an  individual  routine 

You  can  access  toolbox  routines  easily  from  either  assembly 
language  or  high-level  languages.  The  initial  languages  offered 
with  the  Apple  IIGS  Programmer's  Workshop  (APW,  described  in 
Chapter  7)  are  65816  assembly  language  and  C;  macro  libraries 
and  interface  libraries  are  available  for  these  languages.  Any  other 
languages  with  similar  interface  libraries  (such  as  the  TML  Pascal 
used  to  write  the  Pascal  version  of  HodgePodge)  allow  similar 
tool-calling  procedures. 


The  Tool  Locator  is  documented 
fully  under  "The  Tool  Locator"  in 
the  Apple  IIGS  Toolbox 
Reference 


The  Tool  Locator 

Every  time  you  make  a  tool  call,  your  request  goes  through  the 
Tool  Locator,  the  first  tool  set  started  up  at  the  beginning  of  your 
program.  The  Tool  Locator  (in  ROM)  keeps  tables  in  RAM  that 
point  to  the  individual  routines  (which  may  be  in  either  ROM  or 
RAM).  The  pointer  tables  are  kept  in  RAM  so  that  they  may  be 
easily  modified  when  tool  sets  are  updated,  moved  to  ROM  from 
RAM,  or  otherwise  changed.  Your  application  needn't  know  or 
care  where  a  routine  is — it  just  tells  the  Tool  Locator  to  get  it. 


The  input  and  output  parameters 
for  each  assembly-language  tool 
call  are  described  in  the  Apple 
IIGS  Toolbox  Reference 


Calling  from  assembly  language 

The  simplest  way  to  make  tool  calls  from  assembly  language  is  to 
use  macros.  The  macros  provided  with  APW  relieve  you  of  having 
to  remember  the  tool  set  number  and  routine  number  for  each 
call.  Assembly-language  HodgePodge  makes  all  its  calls  with 
macros. 

Make  a  tool  call  as  follows: 

1.  If  the  function  has  any  output,  push  the  correct  amount  of 
space  for  it  on  the  stack. 

2.  If  the  function  has  any  inputs,  push  them  on  the  stack  in  the 
specified  order. 

3.  Invoke  the  appropriate  macro  by  name.  A  macro  name  is  the 
same  as  the  routine  it  calls,  except  that,  by  convention,  it  has  a 
leading  underline  character. 

4.  Check  for  errors,  as  described  under  "Machine  State  on  Return 
from  the  Call,"  later  in  this  section. 

5.  Pull  the  output,  if  any,  from  the  stack. 
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The  names  of  the  parameters  for 
each  tool  routine  in  the  C 
language  are  described  in  the 
Apple  IIGS  Toolbox  Reference. 


You  can  make  an  assembly-language  tool  call  without  macros,  of 
course.  The  method  is  almost  identical  to  that  just  described,  ] 
except  that  instead  of  calling  the  routine  by  name,  you  jump  tdfl 
the  Tool  Locator's  entry  point  ($E1  0000)  with  a  JSL  instruction, 
with  the  tool  set  number  and  routine  number  as  the  high-order 
and  low-order  bytes  in  the  X  register.  All  tool  set  and  routine   I 
numbers  are  documented  in  the  Apple  IIGS  Toolbox  Reference. 
Nevertheless,  it  is  probably  best  to  use  macros  because  names  are 
easier  to  remember  and  read. 


Calling  from  a  high-level  language 

The  interface  libraries  that  allow  C  programmers  to  access  the  I 
Apple  IIGS  Toolbox  are  included  in  APW  C.  Those  libraries 
contain  the  function  definitions  for  the  tools.  The  steps  to  call  a 
routine  are  as  follows.  Other  high-level  languages  will  have  similar 
libraries,  appropriate  to  the  languages'  structures. 

1.  Make  the  routine  accessible  by  using  an  #include  statement 
that  includes  the  appropriate  file  (for  example,  QuickDraw. h 
for  QuickDraw  II  calls).  The  included  file  will  provide  the 
function  declarations  and  the  necessary  constants  and  data 
structures. 

2.  Invoke  the  call  by  entering  its  name  and  supplying  the  correct 
parameters. 

3.  Examine  the  global  error  variable  (_toolErr  in  C, 
ToolErrorNum  in  Pascal)  for  errors,  if  necessary.  If  the 
variable  is  equal  to  zero,  no  errors  occurred;  otherwise,  it 
contains  the  number  of  the  error. 


For  a  complete  description  of 
register  and  flag  states  after  a 
toolbox  call,  see  "Using  the 
Apple  IIGS  Tool  Sets"  in  the  Apple 
IIGS  Toolbox  Reference 


Machine  state  on  return  from  the  call 

When  it  completes  a  call,  a  toolbox  routine  returns  control 
directly  to  the  application  that  called  it.  The  accumulator  contains 
zero  and  the  c  flag  (carry  bit)  is  cleared  to  zero  if  the  call  was 
completed  successfully.  Other  flags  and  registers  have  values 
dependent  on  the  specific  routine  called. 

If  an  error  occurred  during  the  call,  the  carry  bit  is  set  (=1)  and 
the  accumulator  contains  an  error  code  in  this  format: 

high-order  byte  =  tool  set  number 
low-order  byte  =  error  number 
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All  toolbox  error  codes  are 
summarized  in  an  appendix  to 
Volume  II  of  the/App/e  /tes 
Toolbox  Reference. 


Error  passing:  With  this  method,  an  error  can  be  properly 
identified  even  if  it  occurs  during  a  call  to  one  tool  set,  but 
doesn't  actually  show  up  until  a  call  returns  from  another  tool 
set.  For  example,  using  this  method,  a  QuickDraw  II  call  can 
pass  on  an  error  message  from  the  Memory  Manager. 


Handling  events 

The  central  part  of  any  event-driven  program  is  its  main  event 
loop.  As  Figure  2-5  shows  in  the  case  of  HodgePodge,  the  program 
continually  cycles  through  the  event  loop,  waiting  for  an  event  to 
act  upon.  The  application  decides  what  to  do  from  moment  to 
moment  by  looking  at  each  event  and  responding  to  it 
appropriately. 

What  constitutes  an  event?  An  event  is  a  notification  to  the 
program  that  something  has  occurred,  something  that  the 
program  may  wish  to  respond  to.  It  may  be  a  signal  from  outside 
the  program,  such  as  a  keystroke.  Or  it  may  be  something  internal, 
such  as  the  need  to  redraw  part  of  a  window  when  an  overlapping 
window  has  been  moved. 

♦  Interrupts:  An  event  is  different  from  an  interrupt  in  that  it  is 
generated  in  software,  and  that  it  does  not  force  action  by  the 
application.  An  application  can  ignore  any  event  it  does  not 
need  to  act  upon. 

The  Event  Manager  is  the  Apple  IIGS  tool  set  that  notes  these 
occurrences  and  records  them  as  events  (by  creating  event 
records).  For  example,  whenever  the  user  presses  or  releases  the 
mouse  button,  the  Event  Manager  records  the  action  in  an  event 
record.  The  Event  Manager  collects  events  from  a  variety  of 
sources  and  reports  them  to  the  application  on  demand,  one  at  a 
time.  The  Event  Manager  doesn't  necessarily  report  the  events  in 
the  exact  order  they  occur,  because  some  have  higher  priority 
than  others. 

The  Event  Manager  is  also  used  by  other  parts  of  the  toolbox.  For 
instance,  when  HodgePodge  calls  TaskMaster  in  its  main  event 
loop,  TaskMaster  in  turn  calls  the  Event  Manager.  See  "Using 
TaskMaster,"  later  in  this  section. 
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Most  events  are  placed  in  an  event  queue,  which  is  an  ordered  list 
of  event  records.  As  events  occur,  they  are  placed  at  one  end  of 
the  queue;  as  the  application  cycles  through  its  event  loop,  it  pulls 
events  off  the  other  end,  one  at  a  time,  by  making  a  call  such  as 
GetNextEvent. 

♦  TaskMaster:  Rather  than  call  GetNextEvent  directly,  we  suggest  1 
that  your  application  call  TaskMaster  instead.  The  end  result,  1 
however  is  the  same — Taskmaster  calls  GetNextEvent,  which 
pulls  events  off  the  event  queue  as  usual.  See  "Using 
TaskMaster,"  later  in  this  section. 

Figure  3-1  shows  a  simplified  view  of  how  events  are  presented  to  a 
an  application.  All  event  types,  except  switch  events  and  the 
window-related  events  activate  and  update,  pass  through  the  event 
queue.  The  various  types  of  events  are  ordered  by  priority  before 
the  application  sees  them.  Also,  the  application  can  filter  out,  or 
mask,  types  of  events  that  don't  apply  to  a  particular  situation. 
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Event  types 

Events  are  of  various  types.  Some  report  actions  by  the  user; 
others  are  generated  by  the  Window  Manager,  device  drivers,  or 
the  application  itself  for  its  own  purposes.  The  system  handles 
some  events  before  the  application  ever  sees  them,  and  it  leaves 
others  for  the  application  to  handle. 

Each  event's  type  is  described  by  an  event  code,  a  numeric  value 
that  the  Event  Manager  returns  to  the  application  getting  the 
event.  For  programming  convenience,  there  is  also  a  set  of 
predefined  constants  for  these  codes.  Table  3-2  lists  the  codes  and 
constants.  The  first  half  of  the  TaskTable  in  the  assembly- 
language  version  of  HodgePodge's  main  event  loop  (in  the  file 
EVENT  .  ASM)  is  a  code  equivalent  to  Table  3-2;  C  and  Pascal 
HodgePodge,  on  the  other  hand,  use  the  predefined  constants  to 
describe  event  codes. 

Table  3-2 

Event  Manager  event  codes 


Value 

Constant 

Meaning 

0 

nullEvt 

null  event 

1 

mouseDownEvt 

mouse-down  event 

2 

mouseUpEvt 

mouse-up  event 

3 

keyDownEvt 

key-down  event 

A 

(undefined) 

5 

autoKeyEvt 

auto-key  event 

6 

updateEvt 

update  event 

7 

(undefined) 

8 

activateEvt 

activate  event 

9 

switchEvt 

switch  event 

10 

deskAccEvt 

desk-accessory  event 

11 

driverEvt 

device-driver  event 

12 

applEvt 

application-defined  event 

13 

app2Evt 

application-defined  event 

14 

app3Evt 

application-defined  event 

15 

app4Evt 

application-defined  event 
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From  Table  3-2  you  can  see  that  16  is  the  maximum  number  of 
cases  your  main  event  loop  has  to  consider  if  your  application 
calls  GetNextEvent.  If  it  calls  TaskMaster  instead,  many  of  these 
events  are  handled  automatically;  however,  there  is  an  additional 
set  of  codes,  called  task  codes,  returned  by  TaskMaster.  See  "Using 
TaskMaster,"  later  in  this  section. 


Event  records  and  masks 

Every  event  is  represented  by  an  event  record  containing  all 
pertinent  information  about  that  event.  The  event  record  includes 
the  following  information: 

■  What:  the  event  code,  such  as  mouse-down 

■  When:  the  time  the  event  was  posted  (the  tick  count) 

■  Where:  the  location  of  the  mouse  at  the  time  the  event  was 
posted,  in  global  coordinates  (see  "Global  and  Local 
Coordinate  Systems,"  in  this  chapter) 

■  Modifiers:  the  state  of  the  mouse  buttons  and  modifier  keys  at 
the  time  the  event  was  posted,  such  as  Option  key  down 

■  Message:  any  additional,  event-specific  information,  such  as 
which  key  the  user  pressed  or  which  window  is  being  activated 

Some  of  the  Event  Manager  routines  can  be  restricted  to  operate 
on  a  specific  event  type  or  group  of  types;  in  other  words,  some 
event  types  are  enabled  while  all  others  are  disabled.  For  instance, 
instead  of  just  requesting  the  next  available  event,  the  application 
can  specifically  ask  for  the  next  keyboard  event.  It  does  so  by 
supplying  an  event  mask  as  a  parameter.  The  mask  disables  any 
unwanted  event  types. 

There's  also  a  global  system  event  mask  that  controls  which  event 
types,  the  Event  Manager  posts  into  the  event  queue  in  the  first 
place.  When  the  system  starts  up,  the  system  event  mask  is  set  to 
post  all  events. 


Responding  to  events 

Here  are  some  typical  application  responses  to  commonly 
occurring  events. 

♦  TaskMaster:  These  responses  apply  to  a  program  that  uses 
GetNextEvent  in  its  event  loop.  If  you  are  using  TaskMaster 
instead,  see  "Using  TaskMaster,"  later  in  this  section. 
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Mouse  events 

Mouse-down  and  mouse-up  events  occur  when  the  mouse  button 
is  pressed  or  released.  Mouse  movements  cause  the  cursor 
position  to  be  updated,  but  do  not  create  events. 

On  receiving  a  mouse-down  event,  an  application  should  first  call 
the  Window  Manager  to  find  out  where  the  cursor  was  on  the 
screen  when  the  mouse  button  was  pressed,  and  then  respond  in 
whatever  way  is  appropriate.  Depending  on  where  the  cursor  was 
when  the  button  was  pressed,  the  application  may  have  to  call 
toolbox  routines  in  the  Menu  Manager,  the  Desk  Manager,  the 
Window  Manager,  or  the  Control  Manager. 

If  the  application  attaches  special  significance  to  the  user  pressing 
a  modifier  key  or  keys  along  with  the  mouse  button,  it  can 
discover  the  state  of  the  modifier  keys  by  examining  the 
appropriate  flags  in  the  modifiers  field  of  the  event  record. 

If  you  want  your  application  to  respond  to  mouse  double-clicks,  it 
must  detect  them  itself.  It  can  do  so  by  comparing  the  time  and 
location  of  a  mouse-up  event  with  the  time  and  location  of  the 
mouse-down  event  immediately  following  the  mouse-up  event. 

Mouse-up  events  can  be  significant  in  other  ways;  for  example, 
they  can  signal  that  the  user  has  stopped  dragging  the  mouse  after 
selecting  a  group  of  objects.  Most  applications,  however,  can 
ignore  mouse-up  events,  and  handle  dragging  with  other  calls 
such  as  TrackControl. 

♦  HodgePodge:  HodgePodge  does  not  need  to  respond  to  mouse 
events  directly.  See  "Using  TaskMaster,"  later  in  this  section. 

♦  Alternative  pointing  devices:  All  applications  that  use  the  Event 
Manager  work  with  alternative  devices  just  as  they  do  with  the 
mouse.  When  a  device  such  as  a  graphics  tablet  is  being  used, 
its  X-Y  location  and  button  status  appear  in  the  event  records 
in  place  of  the  mouse  information.  Mouse-up  and  mouse-down 
events  are  posted  when  the  alternative  device's  buttons  change 
state. 


Keyboard  events 

Key-down  events  occur  when  character  keys  are  pressed.  Modifier 
keys  (Shift,  Caps  Lock,  Control,  Option,  and  Apple)  generate  no 
keyboard  events  of  their  own — whenever  an  event  is  posted,  the 
state  of  the  modifier  keys  is  reported  in  a  field  of  the  event 
record.  The  character  keys  also  generate  auto-key  events  when  the 
user  holds  them  down. 
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For  a  key-down  event,  the  application  should  first  check  the 
modifiers  field  to  see  whether  the  character  was  typed  with  the 
Apple  key  held  down;  if  so,  the  user  may  have  been  choosing  a 
menu  item  by  typing  its  keyboard  equivalent. 

If  the  key-down  event  is  not  a  menu  command,  the  application 
should  respond  to  the  event  in  whatever  way  is  appropriate.  For  i 
example,  if  one  of  the  windows  is  active,  the  application  could 
insert  the  typed  character  into  the  active  document;  if  none  of  t 
windows  is  active,  it  might  choose  to  ignore  the  event. 

Most  applications  can  handle  auto-key  events  the  same  way  they  j 
handle  key-down  events.  However,  you  may  want  your  application 
to  ignore  auto-key  events  that  invoke  commands  you  don't  want 
continually  repeated. 

♦  HodgePodge:  The  only  key  events  in  HodgePodge  are  the 
keyboard  equivalents  to  menu  commands.  TaskMaster  handles] 
those  events  and  returns  the  menu-selection  information  to 
HodgePodge,  so  HodgePodge  itself  needn't  respond  to  key 
events  at  all. 


See  "Creating  Windows"  in 
Chapter  4  for  a  discussion  of 
window  features. 


Window  events 

To  coordinate  the  display  of  windows  on  the  screen,  the  Window 
Manager  generates  activate  events  and  update  events.  Activate 
events  occur  whenever  an  inactive  window  becomes  active  or  an 
active  window  becomes  inactive.  Update  events  occur  when  all  or 
part  of  a  window's  contents  need  to  be  drawn  or  redrawn,  usually 
as  a  result  of  the  user's  opening,  closing,  activating,  or  moving  a 
window. 

When  the  application  receives  an  activate  event  for  one  of  its  owi 
windows,  the  Window  Manager  will  already  have  done  all  of  the 
normal  housekeeping  associated  with  the  event,  such  as 
highlighting  or  unhighlighting  the  window.  The  application  can 
then  take  any  further  necessary  action,  like  showing  or  hiding  a 
scroll  bar,  or  highlighting  or  unhighlighting  a  selection. 

On  receiving  an  update  event  for  one  of  its  own  windows,  the 
application  is  responsible  for  updating  (redrawing)  the  contents 
of  the  window. 

♦  HodgePodge:  Activate  and  update  events  in  HodgePodge  are 
handled  automatically  through  TaskMaster. 
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Other  events 

Device-driver  events  are  generated  by  device  drivers  in  certain 
situations;  for  example,  an  application  might  set  up  a  driver  to 
report  an  event  when  its  transmission  of  data  is  interrupted. 

A  desk  accessory  event  occurs  whenever  the  user  enters  the 
special  keystoke  (Control-Apple-Escape)  to  invoke  a  classic  desk 
accessory.  See  "Supporting  Other  Desktop  Features"  in  Chapter  5. 

An  application  can  define  as  many  as  four  application- defined 
events  of  its  own  and  use  them  for  any  purpose. 

Switch  events  are  reserved  for  future  use. 

The  Event  Manager  returns  a  null  event  if  it  has  no  other  events  to 
report.  Most  applications  ignore  null  events  and  continue  through 
the  event  loop. 


For  a  full  discussion  of 
TaskMaster.  see  "Window 
Manager"  in  the  Apple  1IGS 
Toolbox  Reference. 


Event  codes  are  listed  in 
Table  3-2. 


Window  regions  are  discussed 
under  "Creating  Windows"  in 
Chapter  4. 


Using  TaskMaster 

TaskMaster  is  a  routine  that  can  handle  many  standard  events. 
Technically,  it  is  part  of  the  Window  Manager,  and  it  handles 
window-related  events  such  as  drawing,  scrolling,  activating,  and 
updating  windows.  It  is  discussed  here  because  it  replaces  the 
GetNextEvent  call  for  an  application,  and  it  also  does  preliminary 
event-handling  for  mouse-down  and  key-down  events. 

When  your  program  calls  TaskMaster  instead  of  GetNextEvent,  the 
following  happens: 

1.  TaskMaster  calls  GetNextEvent. 

2.  If  no  event  is  ready  to  be  handled,  TaskMaster  returns  zero. 

3.  If  an  event  is  ready,  TaskMaster  looks  at  it  and  tries  to  handle  it. 

4.  If  Taskmaster  can't  handle  the  event,  it  returns  the  Event 
Manager  event  code  to  your  application.  The  application  can 
handle  the  event  as  if  the  event  were  coming  from  GetNextEvent. 

5.  If  TaskMaster  can  handle  the  event,  it  calls  standard  toolbox 
functions  to  carry  out  the  task.  For  example,  if  the  user  presses 
the  mouse  button  in  an  active  window's  zoom  region, 
TaskMaster  detects  it  and  calls  TrackZoom;  it  then  calls 
ZoomWindow  if  the  user  actually  selects  the  zoom  region;  and 
finally  it  returns  no  event. 
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When  calling  TaskMaster,  you  pass  a  pointer  to  a  TaskMaster 
record,  the  extended  task  event  record.  The  beginning  of  the  recorJ 
is  the  same  as  an  event  record,  as  described  under  "Event  Records 
and  Masks,"  earlier  in  this  section.  When  TaskMaster  calls 
GetNextEvent,  it  passes  the  provided  pointer,  so  the  event  record 
part  of  that  record  is  set  by  GetNextEvent.  The  record  also  includes 
a  task  mask,  similar  to  the  event  mask;  it  tells  TaskMaster  which 
types  of  events  to  handle. 

Sometimes  TaskMaster  can  handle  an  event  only  up  to  a  point.  If  th 
user  presses  the  mouse  in  the  active  window's  content  region,  Task- 
Master  detects  it,  but  won't  be  able  to  go  any  further,  so  it  tells  the 
application  that  a  mouse-down  event  occurred  in  the  active  win- 
dow's content  region,  and  lets  the  application  decide  what  to  do 
next. 

Because  it  only  partially  handles  some  events,  TaskMaster 
generates  its  own  set  of  "events"  that  a  program's  main  event 
loop  needs  to  respond  to.  Each  type  of  TaskMaster  event  has  a 
task  code,  a  numeric  value  that  TaskMaster  returns  to  the 
application.  Just  as  for  the  Event  Manager  events  described  earlier 
in  this  section,  there  is  a  set  of  predefined  constants  for  these 
codes.  Table  3-3  lists  the  codes  and  constants.  The  second  half  of 
TaskTable  in  the  assembly-language  version  of  HodgePodge's 
main  event  loop  (in  the  file  EVENT .  ASM)  is  a  code  representation 
of  Table  3-3;  C  and  Pascal  HodgePodge,  on  the  other  hand,  use 
the  predefined  constants. 

♦  Note:  Many  of  these  task  codes  are  just  the  results  returned  by 
the  call  FindWindow,  which  TaskMaster  makes  after  calling 
GetNextEvent. 

Table  3-3 

TaskMaster  task  codes 


Value        Constant  Meaning 


16  wlnDesk  in  the  desktop  area 

17  wlnMenuBar  in  the  system  menu  bar 

18  (undefined) 

19  wlnContent  in  a  window's  content  region 

20  wlnDrag  in  a  window's  drag  (title  bar)  region 

21  wlnGrow  in  a  window's  grow  (size  box)  region 

22  wlnGoAway  in  a  window's  go-away  (close  box)  region 

23  wlnZoom  in  a  window's  zoom  (zoom  box)  region 
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24 

wlnlnfo 

25 

wlnSpecial 

26 

wlnDeskltem 

27 

wlnFrame 

28 

wlnactMenu 

$8xxx 

wlnSysWindo' 

in  a  window's  information  bar 

in  the  special  menu  item  bar 
(predefined  items  in  the  Edit  menu) 
in  a  desk  accessory  menu  item  on  the 
Apple  menu 

in  a  window,  but  not  in  any  of  the 
above  parts  of  it 
in  an  inactive  menu  item 
wlnSysWindow  in  a  system  (desk-accessory)  window 

Together,  Table  3-2  and  Table  3-3  show  that  TaskMaster  can  return 
to  your  application  up  to  25  or  so  events  that  your  main  event 
loop  may  have  to  deal  with.  In  most  situations,  though,  TaskMaster 
handles  most  of  them  automatically.  HodgePodge,  as  we  saw  in 
Chapter  2,  responds  only  to  task  codes  17,  22,  and  25 
(wlnMenuBar,    wlnGoAway,  and   wlnSpecial). 

You  should  use  TaskMaster  for  at  least  two  reasons: 

□  It  can  help  you  get  an  application  running  as  quickly  as 
possible,  still  taking  advantage  of  the  standard  user  interface. 
TaskMaster  represents  one  of  the  steps  taken  to  remove  the 
most  tedious  user-interface  chores  from  the  application. 

a  TaskMaster  will  help  assure  upward  compatiblity.  New,  as  yet 
unknown,  features  may  be  added  to  the  Apple  IIGS  system  in 
the  future.  It  may  be  possible  to  incorporate  those  features  by 
modifying  TaskMaster  without  adversely  affecting  past 
applications.  In  other  words,  your  application  may  be  able  to 
use  new  features  without  any  modification  on  your  part. 
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Any  time  your  desktop  application  needs  to  draw  something,  it  uses 
the  Apple  IIGS  tool  set  QuickDraw  II  (and  its  extension,  QuickDraw 
II  Auxiliary).  QuickDraw  II  is  an  adaptation  and  extension  of  the 
Macintosh  toolbox  component  QuickDraw— -it  performs  similar 
operations  but  has  been  enhanced  to  support  Apple  IIGS  color. 

QuickDraw  II  allows  you  to  perform  graphic  operations  easily  and 
quickly.  QuickDraw  draws  text  in  different  fonts  with  styling 
variations  such  as  italics  and  boldface.  It  draws  lines  and  shapes 
of  various  sizes  and  patterns.  It  can  draw  items  in  a  variety  of 
colors  or  in  gray  scales. 
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The  Print  Manager  is  described 
under  "Communicating  With  Files 
and  Devices.'  in  Chapter  5. 


QuickDraw  II  can  draw  to  the  screen  or  to  other  parts  of  Apple 
IIGS  memory.  In  fact,  printing  a  document  with  the  Print  Manager 
involves  using  QuickDraw  to  "draw"  your  document  into  a 
memory  buffer  used  by  the  Print  Manager. 

♦  Note:  For  brevity,  we'll  use  the  terms  QuickDraw  and 

QuickDraw  //synonymously  here.  Unless  otherwise  explicitly 
stated,  QuickDraw  means  the  Apple  IIGS  tool  sets  QuickDraw  n 
and  QuickDraw  II  Auxiliary,  not  the  Macintosh  version. 

To  get  our  bearings,  we'll  first  consider  where  QuickDraw  II  draws. 
Then  we'll  briefy  discuss  how  it  draws,  and  finally  look  at  what  it 
draws.  The  chapter  ends  with  two  examples  that  tie  together 
several  of  the  key  ideas. 


Where  QuickDraw  II  draws 

The  question  of  where  QuickDraw  II  draws  involves  consideration 
of  Apple  IIGS  memory  (including  screen  memory)  as  well  as 
QuickDraw's  own  internal  representation  of  its  drawing  universe. 
These  are  the  main  concepts.- 

□  Drawings  are  stored  in  Apple  IIGS  memory  as  pixel  images, 
ordered  collections  of  bytes  that  represent  rectangular  arrays 
of  pixels.  Screen  memory  contains  a  special  pixel  image-its 
contents  are  displayed  on  the  computer's  monitor. 

□  QuickDraw  II  draws  its  text  and  graphic  objects  on  an  abstract  tw 
dimensional  mathematical  surface  called  the  coordinate  plane 
Points  on  a  plane  are  much  easier  to  visualize  and  manipulate 
than  addresses  in  memory.  Locations  on  the  QuickDraw  II 
coordinate  plane  are  related  to  pixel-image  memory  locations  by 
specific  location  information  supplied  to  QuickDraw. 

□  Quickdraw  draws  most  objects  within  the  context  of  graphic 
ports.  A  port  is  a  complete  drawing  environment  and  defines 
among  other  things,  a  specific  part  of  memory  and  a  specific' 
rectangular  area  on  the  coordinate  plane  where  drawing  can 
occur.  There  can  be  many  open  ports  at  a  time— some  for 
drawing  to  the  screen,  some  for  drawing  to  other  parts  of 
memory.  Different  ports'  drawing  spaces  may  be  separate  from 
each  other  or  they  may  overlap. 
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□  QuickDraw  II  can  be  made  to  clip,  or  constrain  its  drawing,  to 
within  limits  of  arbitrary  size,  shape,  and  location. 

a  By  manipulating  two  independent  sets  of  coordinates  {global 
coordinates  and  local  coordinates),  an  application  can  easily 
control  both  what  gets  drawn  inside  a  port's  drawing  space  and 
where,  on  the  screen  or  other  pixel  image,  that  drawing  space 
appears. 

The  coordinate  plane 

QuickDraw  locates  every  action  it  takes  in  terms  of  coordinates  on 
a  two-dimensional  grid  (Figure  3-2).  The  grid  is  QuickDraw's 
coordinate  plane;  coordinates  on  the  plane  are  integers  ranging 
from  -16K  to  +16K  in  both  the  X-  and  Y-directions.  The  point 
(0,0),  therefore,  is  in  the  middle  of  the  grid.  Note  also  that  grid 
values  increase  to  the  right  and  downward  on  the  plane;  this  is 
different  from  what  you  might  be  used  to,  but  it  is  the  same 
direction  and  order  in  which  video  scan  lines  are  drawn. 

Distances  on  the  grid  are  measured  in  pixels.  Thus  a  10  x  10 
"square"  on  the  coordinate  plane  is  equivalent  to  a  rectangle  10 
pixels  by  10  pixels  on  the  display  screen  (which  would  not  be  a 
square,  of  course,  because  Apple  IIGS  pixels  are  not  square).  Only 
a  very  small  portion  of  the  coordinate  plane  can  be  displayed  on 
the  screen  at  any  one  time — the  plane  is  32,000  pixels  on  a  side, 
whereas  the  screen  can  show  a  maximum  of  640  pixels  by  200 
pixels  at  a  time.  Figure  3-2  shows  the  approximate  size  of  the 
screen  (and  user)  compared  to  the  coordinate  plane. 


Important     QuickDraw  must  not  be  asked  to  draw  outside  the  coordinate 
plane.  Commands  to  draw  outside  this  space  will  produce 
unpredictable  results.  They  won't  generate  errors. 

♦  Macintosh  programmers:  This  conceptual  drawing  space  is  not 
the  same  size  as  that  used  by  QuickDraw  on  the  Macintosh.  On 
the  Macintosh,  the  drawing  space  is  64K  by  64K  pixels  centered 
around  0,0,  thus  making  the  boundary  coordinates  -32K,-32k 
and  32K.32K. 
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Figure  3-2 

The  QuickDraw  II  coordinate  plane 

To  understand  how  QuickDraw  does  its  drawing,  we  need  to  consider 
how  it  represents  some  basic  graphic  elements.  On  the  coordinate 
plane,  grid  lines  are  considered  to  be  infinitely  thin.  A  point  is 
defined  as  the  intersection  of  two  grid  lines,  so  it  also  has  no 
dimensions.  Pixels,  on  the  other  hand,  have  a  definite  size;  they  are 
thought  of  as  falling  between  the  lines  of  the  grid.  The  smallest 
element  that  QuickDraw  can  draw  is  a  pixel,  so  if  it  were  to  draw  a 
point  at  the  location  (3,3)  on  the  coordinate  plane,  it  must  draw  a 
single  pixel.  But  which  one?  Four  pixels  touch  the  point.  QuickDraw 
defines  the  pixel  corresponding  to  each  point  on  the  plane  as  the 
pixel  immediately  below  and  to  the  right  of  the  point.  See  Figure  3-3, 
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Figure  3-3 

Grid  lines,  points,  and  pixels  on  the  coordinate  plane 


Pixel  images  and  the  coordinate  plane 

A  pixel  image  is  an  area  of  memory  that  contains  a  graphic 
image.  The  image  is  organized  as  a  rectangular  grid  of  pixels 
occupying  contiguous  memory  locations.  Each  pixel  has  a  value 
that  determines  what  color  in  the  graphic  image  is  associated  with 
that  pixel. 

♦  Macintosh  programmers:  QuickDraw  IPs  pixel  images  are 
similar  to  Macintosh  QuickDraw's  bit  images.  The  major 
difference  is  that  a  pixel  is  described  by  more  than  a  single  bit. 

As  described  above,  QuickDraw  II  draws  to  the  coordinate  plane. 
However,  the  coordinate  plane  is  really  just  an  abstract  concept. 
Inside  the  Apple  IIGS,  drawing  actually  occurs  by  modifying  pixel 
images — that  is,  by  modifying  the  contents  of  certain  memory 
locations.  In  particular,  drawing  something  visible  on  the  screen 
involves  modifying  the  contents  of  screen  memory. 

The  data  structure  that  ties  the  coordinate  plane  to  memory  is  the 
Loclnfo  (for  location  information)  record.  The  Loclnfo  record 
tells  QuickDraw  where  in  memory  to  draw,  how  the  pixel  image  in 
that  part  of  memory  is  arranged,  and  what  its  position  on  the 
coordinate  plane  is.  In  Pascal,  the  Loclnfo  record  definition  looks 
like  this: 


Loclnfo   =   Record 

portSCB 

Word 

ptrToPixImage 

Ptr 

width 

Integer 

boundsRect 

Rect 

end 
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The  scan-line  control  byte  and 
me  differences  between  640 
mode  and  320  mode  are 
discussed  further  under  "Drawing 
m  Color,  later  in  this  section. 


The  record  consists  of  four  fields: 

'  n°r?rXB  C\repIiCa  °f  the  sca«-lt™  control  byte)  tells 
QuickDraw  how  many  bits  per  pixel  there  arei  tn 
mage-two  for  640  mode,  four  for  320  mode. 

'  ?£roPbiI™&  (or  image  pointer)  is  the  memory  address  of 

con  2!  rh  T?  *  **  firSt  byte  °f  the  P^  ^JX 
contains  the  first  (upper-leftmost)  pixel 

'  "^chtiTnTTI specifies  **  width  Gn  ^'  no« 

so  U  can  tell  wh^  PUCe! image-  QuickDraw  needs  to  know  this 

imaL  width  I,  h         ^  fOW  "  the  ima^  starts-  Ohe 
image  width  must  be  an  even  multiple  of  8  bytes  ) 

'  !n!UndSf CCt  (f°r  b0Undary  rect"ngle)  is  a  rectangle  that  mans 
the  pixel  image  onto  the  coordinate  plane  The  UDO«feZ 
»  the  rectangle  corresponds  to  the  first  p Ll  in  ^  ^X 
lower-nght  corner  of  the  rectangle  describes  the  extenTof  fc 
P-el  image  (as  far  as  QuickDraw  is  concerned)  SeFigu     " 


Image   r— a 
pointer         *■ 


Image  width  - 


Origin  =  (0,0) 


Boundary 
rectangle 


Lower  rigrr 
(16,27) 


Pixel  image  in  memory 
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I— ]     1  byte  (=  2  pixels  in  640  mode) 
Figure  3-4 
Pixel  image  and  boundary  rectangle 


Windows  are  described  further 
under  "Creating  Windows"  in 
Chapter  4. 


GrafPort,  port  rectangle,  and  clipping 

Most  drawing  takes  place  in  conjunction  with  a  data  structure 
called  a  GrafPort  (for  graphic  port).  Each  GrafPort  contains  a 
complete  specification  of  a  drawing  environment,  including  the 
location  information  (Loclnfo  record)  described  above.  In 
addition  to  the  location  information,  a  GrafPort  contains  three 
other  fields  that  restrict  where  drawing  in  a  pixel  image  can  take 
place:  the  port  rectangle,  clipping  region,  and  visible  region. 

The  port  rectangle  (or  portRect)  is  a  rectangle  on  the 
coordinate  plane.  Any  drawing  in  a  GrafPort  occurs  only  inside 
its  portRect.  When  you  look  at  a  window  on  the  screen  in  a 
desktop  application,  its  interior  (everything  but  its  frame) 
corresponds  to  a  port  rectangle. 

The  port  rectangle  can  coincide  with  the  boundary  rectangle  or  it 
can  be  different.  You  can  think  of  it  as  a  movable  opening, 
allowing  access  to  all  or  part  of  the  pixel  image.  As  Figure  3-5 
shows,  QuickDraw  can  draw  only  where  the  boundary  rectangle 
and  port  rectangle  overlap. 


Boundary  rectangle 


Port  rectangle  - 


~^P  L  25755006  J -^ 

m  "Safe 12 

~J             [ilMri 

%J\       ^^ 

t  ^^Vt^/                        jo 

otSmbT 

Figure  3-5 

Boundary  rectangle/port  rectangle  intersection 
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The  clipping  region  (or  clipRgn)  is  provided  for  an  application  tt 
use.  When  a  GrafPort  is  opened  or  initialized,  the  clipping  region 
is  set  to  the  entire  coordinate  plane  (effectively  preventing  any 
clipping  from  occuring).  The  program  can  use  the  clipRgn  in  any 
way  it  wants.  Any  drawing  to  a  pixel  image  through  a  GrafPort 
occurs  only  inside  the  clipping  region. 

The  visible  region  (or  visRgn)  is  normally  maintained  by  the 
Window  Manager.  An  application  can  have  multiple  windows  on 
the  screen,  each  one  associated  with  a  GrafPort.  Windows  can 
overlap,  and  each  port's  visible  region  represents  the  parts  of  the 
window  that  are  visible. 

In  summary,  drawing  occurs  in  a  pixel  image  only  in  the 
intersection  of  the  boundary  rectangle,  port  rectangle,  clipping 
region,  and  visible  region. 

Global  and  local  coordinate  systems 

Everything  is  positioned  in  QuickDraw's  universe  in  terms  of 
coordinates  on  the  plane.  However,  if  you  think  of  multiple  open 
windows  on  the  screen,  you  can  see  that  there  are  at  least  two 
different  ways  in  which  you  might  want  to  locate  objects: 

□  You  may  want  to  specify  where  windows  appear  on  the  screen 
(for  example,  when  they  are  moved). 

□  You  may  want  to  specify  where  objects  appear  within  windows 
(for  example,  when  scrolling),  independently  of  where  on  the 
screen  the  windows  may  be. 

♦  HodgePodge.-  Because  TaskMaster  takes  care  of  all  window 
events  related  to  tasks  such  as  moving  and  scrolling, 
HodgePodge  itself  doesn't  worry  about  coordinates  at  all  when 
it  draws  a  window. 

The  toolbox  needs  global  coordinates  whenever  more  than  one 
GrafPort  share  the  same  pixel  map;  the  global  coordinates  tell 
QuickDraw  exactly  where  every  port  rectangle  is  compared  to 
every  other  one.  The  global  coordinate  system  for  each  GrafPort 
Tho  n  .  .   n.  n      .       ,  1S  that  in  which  ^  boundary  rectangle  for  its  pixel  map  has  its 

ScSS^lu/SJlSft^  °rigin  atuC0'0)  °n  the  coordinate  P1^-  ^r  drawing  to  the  scree, 

corner.  y°u  c*n  think  of  global  coordinates  as  screen  coordinates,  where 

the  upper-left  corner  of  the  screen  is  the  point  (0,0). 
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However,  each  port  also  has  its  own  local  coordinate  system.  For 
example,  when  drawing  into  a  port  it  might  be  more  convenient 
to  think  in  terms  of  distance  from  the  port  rectangle's  origin 
rather  than  the  boundary  rectangle's  origin.  By  defining  the  port 
rectangle  as  starting  at  (0,0),  you  can  base  all  your  drawing 
commands  on  distance  in  from  the  left  edge  and  down  from  the 
top  of  the  portRect. 

That's  convenient  for  drawing  in  a  window,  but  local  coordinates 
are  more  of  a  convenience  than  that.  They  aren't  constrained  to  a 
value  of  (0,0)  for  the  port  rectangle  origin — you  can  set  them  to 
any  coordinate-plane  value.  Why  would  you  want  to?  Because  of 
the  way  drawing  commands  work. 

Suppose  you  are  using  a  window  to  display  portions  of  a 
document  that  is  larger  than  the  port  rectangle  in  size — a  fairly 
common  occurrence.  You  are  using  drawing  commands  that  draw 
the  entire  document,  and  you  know  that's  no  problem  because  the 
drawing  will  be  automatically  clipped  to  the  port  rectangle.  But 
how  do  you  control  which  part  of  the  document  shows  in  your 
window?  You  do  it  by  adjusting  local  coordinates. 

All  QuickDraw's  drawing  commands  are  based  on  the  current 
port's  local  coordinate  system.  So  if  location  (0,0)  in  your 
GrafPort's  local  coordinates  corresponds  to  the  port  rectangle's 
upper-left  corner,  any  time  you  draw  your  document  into  that 
port,  its  upper-left  corner  will  be  displayed.  If  you  define  your 
local  coordinates  differently,  different  parts  of  your  document  will 
appear  in  the  window.  Thus  you  can  think  of  local  coordinates  as 
document  coordinates — the  upper-left  corner  of  the  document 
being  viewed  in  the  port  has  the  value  (0,0)  in  local  coordinates. 
See  Figure  3-6. 
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b.  PortRect  origin  =  (50, 2SC 
in  local  coordinates 


Figure  3-6 

Drawing  different  parts  of  a  document  by 
changing  local  coordinates 


Pen  location  and  other  pen 
characteristcs  are  described 
next,  under  "How QuickDraw  II 
Draws." 


Note:  When  the  local  coordinates  of  a  GrafPort  are  changed,  1 
the  coordinates  of  the  GrafPort's  boundary  rectangle  and 
visible  region  are  similarly  recalculated,  so  (as  noted)  the  poifl 
will  not  change  its  relative  position  on  the  screen  or  in  relation 
to  other  open  ports  on  the  screen. 

However,  when  the  local  coordinates  are  changed  the 
GrafPort's  clipping  region  and  pen  location  are  not 
changed — that  is,  they  appear  to  shift  right  along  with  the 
image  that  is  being  viewed  in  the  port.  It  makes  sense  to  have 
the  pen,  which  is  used  to  modify  the  image  being  viewed,  and 
the  clipping  region,  which  is  used  to  mask  off  parts  of  the 
image  being  viewed,  "stick"  to  it. 
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How  QuickDraw  II  draws 

How  QuickDraw  II  draws  any  of  its  objects  depends  on  the 
drawing  environment  specified  in  the  current  GrafPort.  Each 
GrafPort  record  includes  location  and  clipping  information 
(described  above),  information  about  the  graphics  pen 
(described  next),  information  about  any  text  that  will  be  drawn 
(described  under  "...And  Text  Too,"  later  in  this  section),  and 
other  information  such  as  pen  patterns  to  draw  with. 


The  drawing  pen 

Each  open  port  has  its  own  drawing  pen.  By  means  of  several 
characteristics  modifiable  by  the  application,  the  pen  controls 
where  and  how  drawing  (of  both  text  and  graphics)  occurs. 

Pen  location:  The  pen  has  a  coordinate-plane  location  (in  local 
coordinates).  The  pen  location  is  used  for  drawing  lines  and  text 
only — other  shapes  are  drawn  independently  of  pen  location. 

Pen  size:  The  pen  is  a  rectangle  that  can  have  almost  any  width 
or  height.  Its  default  size  is  1  x  1  (pixels).  If  either  the  width  or 
height  is  set  to  0,  the  pen  will  not  draw. 

Pen  pattern:  The  pen  pattern  is  a  repeating  array  (8  pixels  by  8 
pixels)  that  is  used  like  ink  in  the  pen.  Wherever  the  pen  draws, 
the  pen  pattern  is  drawn  in  the  image.   The  pattern  is  always 
aligned  with  the  coordinate  plane  so  that  adjacent  areas  of  the 
same  pattern  drawn  at  different  times  will  blend  in  a  continuous 
manner. 

Background  pattern:  The  background  pattern  is  an  array  similar 
to  the  pen  pattern.  Erasing  is  the  process  of  drawing  with  the 
background  pattern. 

Drawing  mask:  The  drawing  mask  is  an  8-bit  by  8-bit  pattern  that 
is  used  to  mask,  or  screen  off,  parts  of  the  pattern  as  it  is  drawn. 
Only  those  pixels  in  the  pattern  aligned  with  an  on  (=1)  bit  in  the 
mask  are  drawn.  Figure  3-7  shows  how  a  mask  affects  drawing  with 
a  pattern. 
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Hi 


Figure  3-7 

Drawing  with  pattern  and  mask 


All  eight  pen  modes  (also  called 
transfer  modes)  are  described 
and  diagrammed  under 
"QuickDraw  II"  in  the  Apple  IIGS 
Toolbox  Reference. 


Note  that  drawing  with  a  mask  in  which  every  bit  has  the  value  1  is 
like  drawing  with  no  mask  at  all — all  pen  pixels  are  passed  through 
to  the  image.  Likewise,  drawing  with  a  mask  that  is  all  zeros  is  like 
not  drawing  at  all — all  pen  pixels  are  blocked. 

Pen  mode:  The  pen  mode  specifies  one  of  eight  Boolean 
operations  (COPY,  notCOPY,  OR,  notOR,  XOR,  notXOR,  BIC  and 
notBIC)  that  determine  how  the  pen  pattern  is  to  affect  an 
existing  image.  When  the  pen  draws,  QuickDraw  II  compares 
pixels  in  the  existing  image  with  their  corresponding  pixels  in  the 
pattern,  and  then  uses  the  pen  mode  to  determine  the  value  of  the 
resulting  pixels.  For  example,  with  a  pen  mode  of  COPY,  the 
existing  pixels'  values  are  ignored — a  solid  black  line  is  black 
regardless  of  the  image  already  on  the  plane.  With  a  pen  mode  of 
notXOR,  the  bits  in  each  pen  pixel  are  inverted  and  then 
combined  in  an  exclusive-OR  operation  with  the  bits  in  each 
corresponding  existing  pixel.  Figure  3-8  shows  a  rectangle  drawn 
over  an  existing  circle,  in  both  COPY  and  notXOR  mode. 
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COPY  mode 

Figure  3-8 

How  pen  mode  affects  drawing 


notXOR  mode 


QuickDraw's  shapes  are 
described  next,  under  "What 
QuickDraw  II  Draws." 


Basic  drawing  functions 

QuickDraw  draws  lines  with  the  current  pen  size,  pen  pattern, 
drawing  mask,  and  pen  mode. 

QuickDraw  draws  other  shapes  (.rectangles,  rounded-corner 
rectangles,  ovals,  arcs,  polygons,  and  regions)  in  five  different 
ways: 

■  Frame:  QuickDraw  draws  an  outline  of  the  shape,  using  the 
current  pen  size,  pen  pattern,  drawing  mask,  and  pen  mode. 

■  Paint:  QuickDraw  fills  the  shape,  using  the  current  pen  pattern, 
drawing  mask,  and  pen  mode. 

■  Erase:  QuickDraw  fills  the  shape,  using  the  current  background 
pattern  and  drawing  mask. 

■  Invert:  QuickDraw  inverts  the  pixels  in  the  shape,  using  the 
drawing  mask. 

■  Fill:  QuickDraw  fills  the  shape,  with  a  specified  pattern  and 
using  the  drawing  mask. 

QuickDraw  draws  text  as  described  under  "...And  Text  Too,"  later 
in  this  section. 
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What  QuickDraw  II  draws 

QuickDraw  II  can  draw  a  number  of  graphic  objects  into  a  pixel 
image.  It  draws  text  characters  in  a  variety  of  monospaced  and 
proportional  fonts,  with  styling  variations  that  include  italics, 
boldfacing,  underlining,  outlining,  and  shadowing.  It  draws  straigh 
lines  of  any  length,  width,  and  pattern.  It  draws  hollow  or  pattern- 
filled  rectangles,  circles,  and  polygons.  It  draws  elliptical  arcs  and 
filled  wedges,  irregular  shapes  and  collections  of  shapes.  It  also 
draws  pictures — combinations  of  these  simple  shapes.  Figure  3-9 
summarizes  them. 
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Figure  3-9 

What  QuickDraw  II  draws 


Points  and  lines 


A  point  is  represented  mathematically  by  its  Y-  and  X- 
coordinates — two  integers.  A  line  is  represented  by  its  ends— two 
points,  or  four  integers.  Like  a  point,  a  line  is  infinitely  thin.  When 
drawing  a  line,  QuickDraw  II  moves  the  upper-left  corner  of  the 
pen  along  the  straight-line  trajectory  from  the  current  pen 
location  to  the  destination  location.  The  pen  hangs  below  and  to 
the  right  of  the  trajectory,  as  illustrated  in  Figure  3-10. 
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Starting 
pen  location 


\ 


Pen  size  and 
pattern 


m  \ 


Destination  location 


The  line  as  drawn 

Figure  3-10 

Drawing  lines 

Before  drawing  a  line,  you  can  use  QuickDraw  calls  to  set  the 
current  pen  location  and  other  characteristics  such  as  pen  size, 
mode,  and  pattern. 


Important 


QuickDraw's  data  structure  that  defines  a  point  has  the  vertical 
coordinate  first:  (y,x)  rather  than  (x,y). 


Rectangles 

A  rectangle  (Figure  3-1 1)  is  also  represented  by  two  points:  its 
upper-left  and  lower-right  corners.  The  borders  of  a  rectangle  are 
infinitely  thin.  Rectangles  are  fundamental  to  QuickDraw;  there  are 
many  functions  for  moving,  sizing,  and  otherwise  manipulating 
rectangles. 
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Figure  3-1 1 

A  rectangle 

The  pixels  associated  with  a  rectangle  are  only  those  within  the 
rectangle's  bounding  lines.  Thus  the  pixels  immediately  below 
and  to  the  right  of  the  bottom  and  right-hand  lines  of  the 
rectangle  are  not  part  of  it. 

Rectangles  may  have  square  or  rounded  corners.  The  corners  of  j 
rounded-corner  rectangles  are  sections  of  ovals  (described  next);] 
they  are  specified  by  an  oval  height  and  oval  width. 


Important 


The  QuickDraw  data  structure  that  defines  a  rectangle  has 
coordinates  in  the  following  order:  top,  left,  bottom,  right.  Thus  the 
defining  coordinates  for  the  rectangle  in  Figure  3-1 1  are  (1 ,2,7,6),  li 
may  seem  strange,  but  It  is  consistent  with  the  (y,x)  ordering  of 
points. 


Circles,  ovals,  arcs,  and  wedges 


1 


Ellipses  and  portions  of  ellipses  form  another  class  of  shapes 
drawn  by  QuickDraw  II.  An  oval  is  an  ellipse,  and  it  is  defined  jus 
like  a  rectangle — the  only  difference  is  that  QuickDraw  is  told  to  i 
draw  the  ellipse  inscribed  within  the  rectangle  rather  than  the 
rectangle  itself.  If  the  enclosing  rectangle  is  a  square,  the  resulting 
oval  is  a  circle. 

♦  Pixel  shape:  Remember,  Apple  IIGS  pixels  are  not  square.  A  true 
circle  on  the  screen,  or  a  true  square,  will  have  unequal 
horizontal  and  vertical  dimensions  in  terms  of  pixels. 


90 


Chapter  3:  Using  the  Toolbox  (I) 


Start  angle 


Arc  angle 


An  arc  is  a  portion  of  an  oval,  defined  by  the  oval's  enclosing 
rectangle  and  by  two  angles  (the  starting  angle  and  the  arc  angle), 
measured  clockwise  from  vertical. 

If  an  arc  is  painted,  filled,  inverted,  or  erased,  it  becomes  a 
wedge;  its  fill  pattern  extends  to  the  center  of  the  enclosing 
rectangle,  within  the  area  defined  by  the  lines  bounding  the  arc 
angle. 


Polygons 

A  polygon  is  any  sequence  of  connected  lines.  You  define  a 
polygon  by  moving  to  the  starting  point  of  the  polygon  and 
drawing  lines  from  there  to  the  next  point,  from  that  point  to  the 
next,  and  so  on. 

Polygons  are  not  treated  in  exactly  the  same  manner  as  other 
closed  shapes  such  as  rectangles.  For  example,  when  QuickDraw  II 
draws  (frames)  a  polygon,  it  draws  outside  the  actual  boundary  of 
the  polygon,  because  the  line-drawing  routines  draw  below  and  to 
the  right  of  the  pen  locations.  When  it  paints,  fills,  inverts,  or 
erases  a  polygon,  however,  the  fill  pattern  stays  within  the 
boundary  of  the  polygon.  If  the  polygon's  ending  point  isn't  the 
same  as  its  starting  point,  QuickDraw  adds  a  line  between  them  to 
complete  the  shape. 


Regions 

A  region  is  another  fundamental  element  of  QuickDraw,  one  that 
can  be  considerably  more  complex  than  a  line  or  a  rectangle.  A 
region  can  be  thought  of  as  a  collection  of  shapes  or  lines  (or 
other  regions),  whose  outline  is  one  or  more  closed  loops.  Your 
application  can  draw,  erase,  move,  or  manipulate  regions  just  like 
any  other  QuickDraw  structures. 

You  can  define  regions  by  drawing  lines,  framing  shapes, 
manipulating  existing  regions,  and  equating  regions  to  rectangles 
or  other  regions. 

Regions  are  particularly  important  to  the  Window  Manager,  which 
must  keep  track  of  often  irregularly  shaped,  noncontiguous 
portions  of  windows  in  order  to  know  when  to  activate  the 
windows  or  what  parts  of  them  to  update. 


Drawing  to  the  screen  (and  elsewhere) 


91 


Pictures  are  used  for  transferring 
data  between  applications,  via 
the  Clipboard.  See  "Scrap 
Manager"  in  the  Apple  IIGS 
Toolbox  Reference. 


Pictures 

A  picture  is  a  collection  of  any  QuickDraw  drawing  commands. 
data  structure  consists  of  little  more  than  the  stored  commands 
QuickDraw  plays  the  commands  back  when  the  picture  is  | 
reconstructed  with  a  DrawPicture  call.  A  complex  mechanical 
drawing  produced  from  an  Apple  IIGS  drafting  program  might  1 
saved  as  a  single  QuickDraw  II  picture. 


7exf  modeis  similar  to  pen  mode. 
discussed  earlier  in  this  section. 


...And  text  too 

QuickDraw  II  doesn't  draw  graphic  images  only — it  also  does  all 
text  drawing  for  desktop  applications.  As  an  application 
programmer,  you  can  easily  control  the  placement,  size,  style, 
font,  and  color  of  display  text  with  QuickDraw  calls. 

Your  program  can  provide  QuickDraw  II  with  text  in  a  number  of 
formats: 

■  character:  a  single  ASCII  character  at  a  time 

■  Pascal  string:  a  length  byte  followed  by  a  sequence  of  ASCII 
characters 

■  C  string:  a  sequence  of  ASCII  characters  terminated  by  a  ze 
byte 

■  text  block:  an  arbitrary  number  of  ASCII  characters  in  a  buffer 

However  it  receives  the  text,  QuickDraw  II  draws  it  in  the  same 
way.  It  draws  each  character  at  the  current  pen  location,  with  the 
current  font,  using  the  current  text  mode,  with  the  current 
character  style,  and  using  the  current  foreground  and 
background  colors.  After  drawing  each  character,  QuickDraw 
updates  the  pen  location  for  drawing  the  next  one. 

Providing  QuickDraw  with  various  fonts  and  character  styles  is  the 
job  of  the  Font  Manager.  The  Font  Manager  is  a  tool  set  that 
supports  QuickDraw's  character-drawing  ability  by  providing  an 
application  with  different  fonts  and  styled  variations  of  fonts.  If 
you  want  to  allow  the  user  to  choose  from  all  of  the  fonts 
available  when  the  application  is  run,  or  if  you're  developing  an 
application  that  requires  a  specific  font,  the  Font  Manager  can 
help  you. 
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Characters 

To  help  understand  just  where  text  appears  and  how  much  space 
it  takes  up,  let's  define  a  few  terms.  Refer  to  Figure  3-12. 

Text  fonts  are  made  up  of  individual  characters.  A  character  is 
represented  in  memory  as  a  rectangular  array  of  bits,  called  a 
character  image,  representing  rows  and  columns  of  pixels.  The  on 
(=1)  bits  are  the  foreground  pixels;  the  off '(=0)  bits  are  the 
background  pixels. 

Every  character  in  a  font  has  a  base  line.  The  base  line  is  a 
horizontal  line,  in  the  same  position  for  every  character  in  the 
font.  Any  foreground  pixels  of  a  character  image  that  lie  below 
the  base  line  constitute  the  character's  descender  (characters  like 
p  and  q  have  descenders).  The  ascent  line  is  the  horizontal  line 
just  above  the  top  row  of  a  character  (including  any  blanks);  the 
distance  from  the  base  line  to  the  ascent  line  is  the  font's  ascent, 
and  is  equal  to  the  height  of  the  tallest  character  in  the  font.  The 
descent  line  is  the  line  just  below  the  bottom  row  of  the  character 
(including  any  blanks);  the  distance  from  the  base  line  to  the 
descent  line  is  the  font's  descent,  and  is  equal  in  size  to  the  largest 
descender  in  the  font. 

Each  character's  origin  is  a  point  on  the  base  line  that  is  used  to 
position  the  character  for  drawing.  This  point  need  not  touch  any 
foreground  pixels  of  the  character  image.  When  the  character  is 
drawn,  it  is  placed  in  the  destination  location  so  that  its  character 
origin  coincides  with  the  current  pen  location.  For  many  letters, 
the  character  origin  is  located  on  the  left  edge  of  the  character 
image;  then,  when  the  character  is  drawn,  its  leftmost  foreground 
pixels  fall  just  to  the  right  of  the  pen  location. 

The  font  height  is  the  sum  of  the  ascent  and  descent  heights,  and 
it  is  the  same  for  all  characters  in  a  font.  The  character  width  is 
the  number  of  pixels  the  pen  position  is  to  be  advanced  after  the 
character  is  drawn.  It  includes  the  width  of  the  character  itself  and 
any  needed  space  between  it  and  the  next  character  to  be  drawn. 

Font  height,  ascent,  descent,  character  width,  and  leading  (the 
space  between  lines  of  text)  are  needed  for  calculating  string 
lengths  and  line  spacings  when  you  display  text  on  the  screen. 
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Figure  3-12 

A  character  image 

The  basic  commands  necessary  to  draw  characters  on  the  screen 
are  quite  simple.  Recall  from  Chapter  2  how  HodgePodge  puts  up 
he    One  moment  please..."  message  when  the  program  loads 


MoveTo(20,20) ; 
SetBackColor (0) 
SetForeColor (15) ; 
Drawstring (' One  Moment  Please. 


'). 


{move  pen  to  upper  left   of  screen} 
{background  color  =  black} 
{foreground  color  =  white} 
{write  the  message} 


Once  the  foreground  and  background  colors  are  set,  all  that's 
needed  to  display  a  character  string  is  to  move  the  pen  to  the 
des,red  location,  and  call  the  QuickDraw  routine  DrawString. 

Fonts 

Each  collection  of  related  characters  is  called  a  font.  With  the 
font  manipulation  capabilities  of  the  Font  Manager,  your  Apple 
IIGS  applications  can  show  sophisticated  text  display  in  a  variety 
of  fonts,  sizes,  and  styles.  Y 

Itored  IT"  ^  th%CharaCter  ima*es  ""king  "P  *  font  are 
stored  in  memory  as  a  font  strike.  A  font  strike  is  a  long 

rectangular  array  of  bits  consisting  of  the  character  images  of 

every  defined  character  in  the  font,  placed  sequentially  in  order 

of  increasing  ASCII  code.  The  character  images  in  the  font  strike 

abut  each  other;  no  blank  columns  are  left  between  them 
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Figure  3-13 

Part  of  a  font  strike 

A  given  font  strike  need  not  contain  a  character  image  for  every 
possible  ASCII  code.  The  font  may  leave  some  characters 
undefined;  these  are  called  missing  characters.  Immediately 
following  the  last  defined  character  in  the  font  strike  is  a  character 
known  as  the  missing  symbol,  which  is  to  be  used  in  place  of  any 
missing  character.  In  many  fonts  the  missing  symbol  is  a  hollow 
rectangle;  in  the  Apple  IIGS  system  font,  it's  a  white-on-black 
question  mark.  Whenever  the  QuickDraw  II  text-handling  routines 
encounter  a  missing  character,  they  substitute  the  missing  symbol 
for  the  character. 

Choosing  a  font:  Fonts  for  the  Apple  IIGS  are  grouped  into  font 
families.  Individual  fonts  within  families  can  have  various 
characteristics,  as  noted  in  the  following  list.  When  your 
application  requests  a  font,  the  Font  Manager  searches  all 
available  fonts  and  chooses  the  one  that  most  closely  matches  the 
request,  in  these  categories: 

Ihe  family  name  of  the  Apple  llss  ■   Name:  Every  font  family  has  a  name.  The  name  refers  to  both 

system  font  (in  ROM)  is  Shaston  plain-styled  characters  of  all  sizes,  and  any  styled  variations, 

such  as  bold  or  italics. 

■  Number:  Every  font  family  has  a  number,  also  independent  of 
point  size  or  style  modifications.  Every  family  number  is 
unique,  and  corresponds  to  a  single  family  name.  $0000 
represents  the  system  font. 

Whenever  an  application  requests  a  font  whose  family  number 
is  not  available,  the  Font  Manager  substitutes  the  system  font. 

■  Size:  An  individual  font  has  a  size,  described  in  points.  A  point 
is  a  typesetting  measure  equal  to  about  l/72nd  of  an  inch. 
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The  Font  Manager  can  provide  both  real  and  scaled  fonts  A 
real  font  is  one  that  actually  exists  on  disk  at  a  particular  poin 
size.  Conversely,  a  scaled  font  is  one  that  was  enlarged  or 
reduced  by  calculation  from  a  font  of  a  different  size  The  Font 
Manager  may  scale  a  font  from  an  existing  size  if  the  requested 
size  is  not  available.  Real  fonts  generally  have  a  better  screen 
appearance  than  scaled  fonts. 

Style:  An  individual  font  also  has  a  style  (or  combination  of 
styles).  The  presently  defined  styles  are 

□  Plain 
d  Bold 

a  Italic 

□  Underline 

□  Outline 
n  SI 


I 


There  are  two  different  ways  to  obtain  styled  variations  of  font 
First,  the  Font  Manager  will  provide  a  styled  font  if  one  is 
available— one  whose  characters  are  designed  with  (for 
example)  bold  or  italic  styling.  Second,  QuickDraw  II  can  style 
a  font— that  is,  it  can  produce  a  bold  or  italicized  version  of  a 
plain-styled  font.  In  fact,  it  can  produce  any  combination  of  the 
denned  styles. 

•  Note:  Fonts  that  are  already  styled  will  not  be  further  styled  (in 
the  same  manner)  by  QuickDraw  II,  regardless  of  the  text 
styling  selected.  For  example,  an  italic  font  is  not  further 
italicized  if  that  option  is  selected  on  a  style  menu.  However  it 
could  be  underlined. 

Underlining:  Text  cannot  be  underlined  unless  the  font's 
characters  have  a  descent  value  (distance  between  the  base  line 
and  descent  line)  of  at  least  2  pixels.  The  Apple  IIGS  system 
font  (Shaston  8)  has  a  descent  value  of  1,  and  therfore  cannot 
be  underlined. 


Important 


thf  cv£cm?    k9!'  IO°kS  f°r  fonts  in  the  ^directory  called  FONTS/  ii 
the  SYSTEM/  subdirectory  on  the  system  disk.  This  subdirectory  must 
con  am  all  fonts  (except  the  system  font)  that  are  to  be  avaX  to 
applications.  See  Appendix  C.  "vanaoie  to 
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DoChooseFont  is  in  the  source  file 
FONT.PAS. 


Your  application  can  allow  the  user  to  select  a  font  by  calling  the 
Font  Manager  routine  ChooseFont.  That's  what  HodgePodge  does 
in  its  DoChooseFont  subroutine,  called  from  the  routine  DoMenu: 


function  DoChooseFont:    Boolean; 


{begin  DoChooseFont...} 


var    theFont    :  FontID; 

dummy     :  Integer; 

tmpPort    :  GrafPortPtr; 

tmpPortRec:  Graf Port; 

famName    :  Str255; 


begin 


tmpPort  :=  GetPort; 
OpenPort (QtmpPortRec) ; 

theFont  :=  ChooseFont (desiredFont, 0) ; 

if  Longlnt (theFont)  -  0  then 

DoChooseFont  :=  FALSE 
else 
begin 
desiredFont  :=  theFont; 
dummy  :=  GetFamlnfo (dDesiredFont . famNum, 

famName) ; 
myReply . filename  : = 

concat (famName, 
i  i 

IntToString 

(desiredFont .fontsize) ) ; 
DoChooseFont    :=  TRUE; 
end; 

ClosePort (StmpPortRec) ; 
SetPort (tmpPort) ; 


end; 


{Save  current  port...} 

{...and  open  new  one,  so  that 

the  current  port  is  not  affected} 
{Bring  up  a  dialog  prompting 

the  user  to  select  a  font} 
{If  the  user  cancels...} 
{DoChooseFont  unsuccessful} 


{Update  global  variable  DesiredFont} 
{Get  the  font  name  from  its  number...} 

{...and  put  the  font  name  and  size  in...} 

{...global  variable  myReply . filename } 
{DoChooseFont  completed  successfully} 
{end  of  IF  user  doesn't  cancel} 

{Close  the  temporary  port...} 
{..And  restore  the  current  port} 
{End  of  DoChooseFont} 


ShowFont  is  listed  under 
"Displaying  Documents  in  Ports: 
Two  Examples,"  later  In  this 
section. 


The  ShowFont  subroutine  in  HodgePodge  is  an  example  of  how 
to  draw  text  strings  in  a  specific  font  with  QuickDraw.  It  is  called 
when  a  font  window  is  first  opened  and  also  whenever  it  needs  to 
be  redrawn. 
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Drawing  in  color 

The  video  display  hardware  of  the  Apple  IIGS  includes  advanced 
color  capabilities.  Although  tool  calls  make  it  unneccessary  for 
you  to  manipulate  the  hardware  directly,  knowledge  of  a  few 
background  concepts  will  help  you  understand  the  way  QuickDraw  1 
II  manipulates  the  colors  on  the  screen. 

The  Apple  IIGS  offers  two  Super  Hi-Res  graphics  modes.  Both 
modes  have  200  scan  lines,  but  the  scan  lines  differ  in  horizontal 
resolution — one  mode  has  320  pixels  (the  color  of  each  specified 
by  4  bits),  and  the  other  has  640  pixels  (the  color  of  each  specified  I 
by  2  bits).  In  changing  from  320  mode  to  640  mode,  the  horizontal  1 
resolution  is  doubled  at  the  expense  of  dividing  the  color  resolution 
by  four. 

Both  modes  use  a  chunky  pixel  organization  (in  which  the  bits  for 
a  given  pixel  are  contained  in  adjacent  bits  within  one  byte),  as 
opposed  to  bit  planes  (in  which  adjacent  bits  in  memory  affect 
adjacent  pixels  on  the  screen).  Therefore  the  4  bits  of  a  pixel  in 
320  mode  are  in  the  same  memory  locations  as  the  4  bits  of  a 
pair  of  adjacent  2-bit  pixels  in  640  mode. 

Colors  on  the  Apple  IIGS  are  determined  from  master  color  values, 
which  are  mathematical  combinations  of  the  primary  red,  blue,  and 
green  hues  available  on  a  color  monitor.  A  master  color  value  is  a 
2-byte  number.  The  low-order  nibble  of  the  low-order  byte,  controls 
the  intensity  of  the  color  blue.  The  high-order  nibble  of  the  low- 
order  byte,  controls  the  intensity  of  the  color  green.  The  low-order 
nibble  of  the  high-order  byte,  controls  the  intensity  of  the  color  red 
The  high-order  nibble  of  the  high-order  byte  is  not  used.  Figure  3-14 
illustrates  the  format  of  a  master  color  value. 
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Value: 
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green 

blue 

Figure  3-14 

Master  color  value  format 

A  3-digit  hexadecimal  number  can  describe  each  master  color, 
with  one  digit  ($0-$F)  for  each  primary  color.  Thus  a  master 
color  value  of  $000  denotes  black,  $FFF  is  white,  $00F  is  the 
brightest  possible  blue,  $080  is  a  medium-dark  green,  and  so  on. 
Because  each  primary  color  has  16  possible  values,  a  total  of  4096 
colors  are  possible. 
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At  any  one  time,  the  Apple  IIGS  can  display  only  a  small  subset  of 
all  possible  colors.  An  application  specifies  its  colors  by 
constructing  one  or  more  color  tables,  short  lists  of  the  available 
colors  for  any  one  pixel. 

Color  tables  and  palettes 

Applications  cannot  specify  pixel  colors  directly  by  using  master 
color  values.  Pixels  contain  only  2  or  4  bits,  and  it  takes  12  bits  to 
specify  a  master  color  value.  That's  why  color  tables  are 
necessary.  A  color  table  is  a  table  of  16  2-byte  entries.  Each  entry 
in  the  table  is  a  master  color  value;  any  of  the  4096  possible  color 
values  may  appear  in  any  position  in  the  color  table. 

An  application  determines  the  color  of  a  given  pixel  by 
specifying  an  offset  into  the  color  table.  The  number  of  bits  used 
to  describe  a  pixel  limits  how  far  into  the  table  it  can  reach.  The 
colors  available  to  the  application,  as  specified  in  its  color  tables, 
constitute  its  palette.  See  Figure  3-15. 

Pixels  in  320  mode  are  represented  in  memory  by  4-bit  integers. 
For  each  pixel,  that  4-bit  value  is  used  as  an  offset  in  a  color  table. 
With  4  bits,  there  are  16  possible  pixel  values,  so  the  palette  in  320 
mode  is  16  colors — the  entire  color  table. 

Pixels  in  640  mode  are  represented  in  memory  by  2-bit  integers. 
With  2  bits,  there  are  4  possible  pixel  values  to  offset  into  the 
color  table,  so  the  palette  in  640  mode  consists  of  only  4  colors. 
That  would  seem  to  leave  three-quarters  of  the  color  table  unused 
in  640  mode,  and  severely  restrict  the  use  of  color,  but  it's  not 
really  so. 

In  the  first  place,  each  4  adjacent  pixels  in  640  mode  use  4 
different  parts  of  the  same  color  table;  a  color  table,  then,  consists 
of  four  mini-palettes,  which  needn't  have  the  same  sets  of  master 
colors.  Therefore,  although  each  individual  pixel  in  640  mode  can 
have  one  of  only  four  colors,  groups  of  four  pixels  can  have  a 
total  of  16  colors  from  which  to  choose.  How  to  use  this  ability  to 
create  a  large  variety  of  colors  is  described  under  "Dithered 
Colors  in  640  Mode,"  later  in  this  section. 
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Figure  3-15 

Accessing  the  color  table  in  320-  and  640  mode 

An  application  may  construct  as  many  as  16  different  color  tables 
to  choose  from.  Each  of  the  200  scan  lines  in  Super  Hi-Res 
graphics  can  use  any  one  of  the  16  tables.  For  each  scan  line,  a 
scan  line  control  byte  (SCB)  decides  which  color  table  is 
active.  The  SCB  also  controls  screen  display  mode  (320  or  640), 
interrupt  mode  (whether  or  not  to  generate  an  interrupt  during 
horizontal  blanking),  and  fill  mode  (whether  or  not  pixel 
values  of  zero  can  be  used  to  fill  areas  of  color  in  320  mode). 


Standard  color  palette  (320  mode) 

The  standard  palette  (the  default  color  table)  for  320  mode  is 
shown  in  Table  3-4.  In  the  table,  offset  means  positon  in  the  colori 
table,  and  value  means  master  color  value,  the  hexadecimal  value 
controlling  the  fundamental  red-green-blue  intensities. 
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Table  3-4 

Standard  palette— 320  mode 


Offset  Color  Value 


0  Black  0  0  0 

1  Dark  Gray  7  7  7 

2  Brown  8  4  1 

3  Purple  7  2  C 

4  Blue  OOF 

5  Dark  Green  0  8  0 

6  Orange  F  7  0 

7  Red  D  0  0 

8  Beige  F  A  9 

9  Yellow  F  F  0 

10  Green  0  E  0 

11  Light  Blue  4DF 

12  Lilac  D  A  F 

13  Periwinkle  Blue         7  8  F 

14  Light  Gray  C  C  C 

15  White  FFF 

The  standard  palette  was  selected  because  of  its  flexibility  and 
appearance;  we  recommend  that  you  use  it  unless  you  have  a 
specific  need  to  change  it. 

Dithered  colors  in  640  mode 

As  explained  above,  only  four  colors  are  available  for  each  pixel  in 
640  mode.  But  when  small  pixels  of  different  colors  are  next  to  eacl 
other  on  die  screen,  their  colors  blend.  For  example,  a  black  pixel 
next  to  a  white  pixel  appears  to  the  eye  as  a  larger  gray  pixel.  By 
cleverly  choosing  the  entries  in  the  color  table  we  can  make  more 
colors  appear  on  the  screen.  This  process  is  called  dithering. 

At  the  same  time,  in  order  to  preserve  the  maximum  resolution  for 
displaying  text,  both  black  and  white  must  be  available  for  each 
pixel.  This  leaves  only  two  remaining  colors  per  pixel  to  choose 
from,  which  seems  like  a  severe  restriction.  But  with  dithering,  you 
can  have  640-mode  resolution  for  text  and  still  display  16  or  more 
colors,  if  you  are  willing  to  resort  to  a  few  simple  tricks. 
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Consider  the  following  byte  with  four  pixels  in  it: 

Bit  value  |_0  i  1  I  0  h 

Pixel  number 


fn  each  o   thp      f       m    '  WUch  iS  ™  index  int°  the  se™nd^ 
in  each  of  the  color  table's  minipalettes  (as  shown  in  Figure  3  15) 
So  pxei  rs  color  „  determined  b    en       1  J»  e  ^ 

color  1S  determmed  by  entry  1  in  minipalette  2,  and  so  on  IfwTuse 
he  standard  640-mode  color  table  (shown  in  Table  3-5)  then  pi 

$D00)  Th    aPPear„blUe  C$00FX  Md  piX6lS  2  and  4  will  appeal    ' 
(SDOO).  The  eye  will  average  these  colors  and  see  violet. 

IahneTssumfind^nent,COmbinati0nS  °f  ^  that  a  ^  <*  P** 

Table  3-5 

Standard  palette-640  mode 


Offset 


0 
1 
2 
3 

4 
5 
6 
7 

8 
9 
10 
11 

12 
13 
14 
15 


Color 

Black 
Blue 
Yellow 
White 

Black 
Red 
Green 
White 


Black 
Blue 
Yellow 
White 

Black 
Red 
Green 
White 


Value 

(minipaleffe  offset) 

000 

0 

OOF 

1 

FFO 

2 

FFF 

3 

000 

0 

D00 

1 

0E0 

2 

FFF 

3 

000 

0 

OOF 

1 

FFO 

2 

FFF 

3 

000 

0 

D00 

1 

0E0 

2 

FFF 

3 
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Black  and  white:  Note  that  the  entries  in  the  minipalettes  for 
the  standard  640-mode  color  table  are  set  up  so  that  black  and 
white  appear  in  the  same  positions  in  each  palette.  This 
arrangement  provides  pure  black  and  white  at  full  640 
resolution,  allowing  crisper  text  display. 


Displaying  documents  in  ports:  two  examples 

Commonly  you  may  want  to  have  an  application  open  up  a  port 
and  display,  within  its  port  rectangle,  a  portion  of  a  previously 
created  drawing  or  text  document.  You  might  even  want  to  allow 
the  user  to  scroll  around  within  that  document,  showing  different 
parts  of  it  in  the  port. 

This  is  not  as  complicated  as  it  sounds.  We'll  just  give  you  a  brief 
idea  here  of  two  simple  ways  to  approach  it — two  of  the  methods 
used  in  HodgePodge.  Please  consult  the  Apple  IIGS  Toolbox 
Reference  for  more  details.  See  also  "Creating  Windows"  in 
Chapter  4  for  more  information  on  scrolling. 

♦  Note:  Ultimately,  you  are  likely  to  want  to  let  the  user  alter  z 
part  of  a  document  while  viewing  it  in  a  port,  and  be  sure  that 
the  changes  made  are  reflected  in  updates  to  the  document 
itself.  HodgePodge  does  not  have  that  capability;  you  may  want 
to  add  it  as  a  programming  exercise. 

Pixel  images 

The  keys  to  displaying  a  portion  of  a  pixel  image  in  a  GrafPort  are 
the  QuickDraw  (and  QuickDraw  Auxiliary)  routines  that  copy 
pixels  from  one  region  to  another.  One  is  CopyPixels;  the  one  we 
use  here  is  PPToPort  (for  Paint-Pixels-to-Porf) .  PPToPort  transfers 
pixels  from  a  given  source  pixel  image  to  the  current  GrafPort's 
pixel  image  (the  destination  pixel  image).  To  use  this  method  to 
view  a  document  you  might  try  the  following: 
1.  Define  a  Loclnfo  record  that  describes  the  offscreen  pixel 
image  you  wish  to  display. 

2  Open  an  onscreen  GrafPort;  its  boundary  rectangle  is  the 
screen  image  boundary  rectangle.  Make  its  port  rectangle  any 
size  you  wish,  up  to  full  screen  size.  Now  anything  you  draw  into 
that  port  will  be  visible  on  screen. 

3.  Set  your  port's  local  coordinates,  to  control  which  portion  of 
the  image  you  want  to  display  first.  To  show  the  upper-left 
corner  of  the  image,  set  the  port  rectangle's  origin  to  (0,0). 
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Paintlt  is  in  the  source  file 
PAINT.PAS. 


4.  Call  PPtoPort  to  copy  the  offscreen  image  onto  the  onscreen  I 
rectangle.  The  call  asks  QuickDraw  to  draw  the  entire  image,  but 
because  drawing  is  automatically  clipped  to  the  port  rectangle, 
you  only  get  the  part  you  want. 

HodgePodge  uses  PPtoPort  to  draw  the  contents  of  its  picture 
windows.  Here  is  the  routine  that  does  the  drawing  (Paintlt, 
called  by  the  routine  Paint)  : 


procedure  Paintlt    (pict :    Handle); 

var  srcLoc    :    Loclnfo; 

srcRect:    Rect; 

begin 

HLock(pict) ; 

with   srcLoc   do 
begin 
portSCB  :=   $0080; 

ptrToPixImage    :=  pict"; 
width  :=   160; 

SetRect (boundsRect, 0, 0, 640, 200); 
end; 


{begin  Paintlt...} 

{a  Loclnfo  record} 
{a  rectangle} 


{Lock  the  image's  memory  block} 

{Define  the  Loclnfo  fields:} 

{set  640  mode} 
{pointer  to  the  image} 
{row-width  of  image  in  bytes} 
{boundary-rectangle  coordinates} 


SotRect (srcRect,  0,0,  640,  200)  ; 

PPToPort (srcLoc , 

srcRect, 
0, 
0, 
srcCopy) ; 


HUnLock(pict) 


end; 


{rectangle  to  copy  FROM} 

{Copy  pixels  from  this  Loclnfo...} 
{...and  this  source  rectangle...} 
{...to  location  (0,0)  in  the  current...}: 
{ ...Graf Port '  s  local  coordinates...} 
{...with  a  pen  mode  of  COPY} 

{Unlock  the  image  now  that  we're  done} 
{End  of  Paintlt} 


Text  documents 

Many  documents,  such  as  text  files,  have  no  explicit  pixel  image 
in  memory  that  represents  the  contents  of  the  file.  If  you  want 
your  application  to  permit  displaying  or  scrolling  through  such  a 
document  in  a  port,  you  wouldn't  transfer  pixels  from  one  image 
to  another — you  would  draw  directly  into  the  port  you  opened. 
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The  pixel-based  image  of  a 
document  as  seen  in  a  window  is 
commonly  called  the  data  area. 
See  "Creating  Windows"  in 
Chapter  4. 


ShowFont  is  in  the  source  file 
FONT.PAS. 


Nevertheless,  the  concept  of  local  coordinates  is  still  important 
and  is  used  identically.  Instead  of  using  an  actual  pixel  image 
somewhere  in  memory,  you  need  to  calculate  a  "virtual  image"  of 
the  document.  You  need  to  know  its  exact  size,  in  pixels,  and  be 
able  to  place  it  properly  in  relation  to  the  port  rectangle  so  that 
the  part  you  want  displayed  is  within  the  rectangle.  Then  you  can 
set  local  coordinates  accordingly  and  draw  the  document  to  the 
port,  knowing  that  it  will  be  clipped  appropriately. 

♦  Note:  Pascal  HodgePodge  calculates  document  height  when  it 
creates  a  text  window,  but  it  simply  assumes  a  particular  width. 
Assembly-language  and  C  versions  of  HodgePodge,  on  the 
other  hand,  calculate  document  width  also,  in  the  routine 
FindMaxWidth.  See  Appendixes  E  and  F. 

HodgePodge  calculates  line  height  in  pixels  and  locates  all 
drawing  in  relation  to  the  document  origin— point  (0,0)—  when  it 
displays  the  contents  of  a  font  window  using  the  routine 
ShowFont.  The  routine  first  installs  a  font  (loads  it  into  memory), 
then  calculates  line  height,  and  then  uses  that  information  to  draw 
the  text.  ShowFont  is  called  from  the  routine  DispFontWindow. 


-e  ShowFont (TheFont ID: 

Font ID; 

I sMono : 

Boolean) 

fontlnfo      : 

FontlnfoRec; 

currHeight : 

Integer- 

i»  J                  : 

Integer; 

theCh             : 

Integer; 

currPt           : 

Point; 

fontStr        : 

Str255; 

{Begin  ShowFont...} 

{a  record  to  hold  font  information} 
{line  height  of  selected  font} 


{string  variable  to  hold  characters} 


begin 

InstallFont (TheFontID, 0) ; 
GetFontlnfo (fontlnfo) ; 

currHeight    :=  fontlnfo. ascent   + 

fontlnfo. descent  + 
fontlnfo. leading; 

i    :=  GetFamlnfo (TheFontID. f amNum, fontStr) 
fontStr    :=  concat (fontStr, '    ', 

IntToString 
(TheFontID. fontsize) ) ; 

i    :=   GetFontFlags; 
if  IsMono   then 

i   :=  BitOr(i,$0001) 
else 

i  :=  BitAnd(i,$0000); 
SetFontFlags  (i) ; 


{Load  the  font  into  memory...} 
{...and  store  its  data  in  Fontlnfo} 


{Calculate  the  font's  line  height} 
{Get  the  font's  name...} 


{...make  a  title  string  with 

font's  name  and  size} 

{Get  current  mono/prop,  setting} 

{If  menu  selection  says  "mono"...} 

{...set  bottom  bit  =  fixed  width} 

(Otherwise: } 

{Clear  bottom  bit  =  proportional} 

{Store  result  in  font  flags} 
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MoveTo (5, currHeight) ; 
Drawstring (fontStr) ; 


{Now  draw  the   lines    of   text:) 

{Move  pen  to   start   of  first   line} 
{Draw  the  title   string} 


MoveTo  (5,  currHeight *3) ;  KHr<  a    ,. 

DrawString(  P                 '    move  to   start  of  next} 

>tv,=         •    v  i_             *  {Draw  second  line} 

Trie  quick  brown  fox  jumps  over  the  lazy  dog. •) ■ 
MoveTo (5, currHeight*4); 

ra"QK "nS[!                  ,  {Draw  third  line} 
She   sells   sea   shells   down  by  the   sea   shore.1); 


MoveTo (5, currHeight*5) ; 
for  i    :=   0   to  7    do 
begin 
GetPen(currPt)  ; 

MoveTo (5, currPt.v  +   currHeight) 
theCh    :=  i    *   32; 
for  j    :=  1    to  32   do 
begin 
fontStrfj]     :=  chr  (theCh) ; 
Inc (theCh) ; 
end; 

fontStrfO]     :=  chr(32); 
Drawstring (fontStr) ; 


end; 


end; 


{Now  draw  all  characters  in  the  font:} 
{For  each  of  7  lines...} 

{starting  at  current  pen  location...} 
{...drop  to  start  of  next  line} 
{...calculate  starting  character...} 
{For  each  of  32  chars,  in  the  line...} 

{put  the  character  into  fontStr} 

{go  to  the  next  character} 

{end  filling  fontStr  for  this  line} 

{Now  set  the  length  byte  to  32...} 
{...and  draw  the  character  string} 

{end  of  drawing  the  line} 
{End  of  ShowFont} 
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Using  the  Toolbox  (II) 
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This  chapter  continues  the  discussion  of  the  Apple  IIGS  Toolbox. 
Starting  up,  handling  events,  and  basic  drawing  to  the  screen  were 
covered  in  Chapter  3;  here  we  look  at  tool  sets  that  help  you 
create  windows,  dialog  boxes,  and  alerts.  Chapter  5  presents  the 
remaining  tools. 


Creating  windows 


A  window  is  basically  a  port  rectangle  with  a  frame;  when  you 

^rTctXleo^ Z°:eTn  "ff?  *  ™ t™  ^  "T  *  ^^  *°°*  ^  SOme 

Chapter  3.  additional  information  that  makes  a  window.  When  you  draw  into 

a  window,  you  are  drawing  into  the  port  rectangle  of  the  GrafPort 

associated  with  that  window.  The  Window  Manager  is  the  Apple 

IIGS  tool  set  that  creates  these  "ports  with  frames,"  keeps  track  of 

their  characteristics,  and  makes  it  easy  for  you  to  deal  with  the 

fact  that  there  may  be  multiple,  movable,  scrollable,  overlapping 

windows  on  the  screen  at  any  one  time. 


Window  basics 


To  begin  to  understand  windows,  let's  look  at  some  basic 
concepts,  specifically: 

□  how  windows  relate  to  GrafPorts 

□  what  data  structures  define  a  window's  features 

□  what  types  of  window  frames  and  controls  are  available 

a  what  window  regions  are,  and  how  the  content  region  of  a 
window  relates  to  its  data  area 


Windows  and  GrafPorts 

It's  easy  to  use  windows— a  window  is  a  port  that  your  application 
can  draw  into  conveniently  with  QuickDraw  II  routines.  When  you 
first  create  a  window,  the  pixel  image  and  boundary  rectangle  for 
its  GrafPort  correspond  to  the  entire  screen  (QuickDraw  II's 
default  assignment),  and  the  pen  pattern  and  other  characteristics 
are  also  the  default  values  for  a  GrafPort.  You  can  accept  these 
default  characteristics  unchanged,  or  you  can  easily  change  them 
with  QuickDraw  II  routines. 
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But  there  is  more  to  a  window  than  the  port  in  which  the 
application  draws.  The  other  part  of  a  window  is  called  the 
window  frame.  It  usually  surrounds  the  window,  and  is  not  part  of 
the  window's  GrafPort.  You  don't  draw  into  the  window's  frame 
area  directly — the  Window  Manager  takes  care  of  that. 

♦  Note:  For  drawing  window  frames,  the  Window  Manager  uses  a 
GrafPort  that  has  the  entire  screen  as  its  port  rectangle;  this 
GrafPort  is  called  the  Window  Manager  port. 


For  examples  of  the  use  of  these 
fields  in  HodgePodge,  see  the 
listings  of  Paint  or 

DIspFontWindow  under  "Handle 
Specific  Events"  In  Chapter  2.  See 
also  the  listing  of  the  routine 
DoTheOpen.  under  "Opening  a 
Window:  An  Example,"  later  in 
this  section. 


Window  records  and  templates 

The  Window  Manager  keeps  all  the  information  it  requires  for  its 
operations  on  a  particular  window  in  a  window  record.  The  record 
consists  of  the  window's  GrafPort  record  plus  other  information 
the  Window  Manager  needs  to  manage  windows.  Application 
access  to  record  information  is  restricted  to  calls  through  the 
Window  Manager  and  directly  to  the  GrafPort  part  of  the  window 
record.  As  in  the  case  of  any  toolbox  records,  accessing  their 
fields  through  calls  instead  of  reading  them  directly,  helps  to 
guarantee  that  your  application  will  remain  compatibile  with 
future  toolbox  revisions. 

When  you  create  a  new  window  with  the  NewWindow  call,  you  pass 
the  Window  Manager  a  NewWindow  parameter  list,  a  template  that 
defines  the  details  of  the  window  to  be  created,  including  its  size 
and  location  and  what  controls  it  will  have.  The  Window  Manager 
uses  this  information  to  construct  the  window's  record.  Three 
fields  in  the  NewWindow  parameter  list  are  worth  specific 
mention: 

a  wFrame,  a  set  of  bit  flags  that  controls,  among  other  things, 
whether  the  window  is  to  have  frame  scroll  bars.  Simply  by 
setting  bits  in  this  field,  HodgePodge  specifies  that  its  windows 
are  to  have  both  horizontal  and  vertical  scroll  bars. 

D  wRefCon,  which  can  have  any  contents  an  application  wants. 
HodgePodge  uses  this  field  to  store  a  pointer  to  information 
about  the  type  of  window  (font  or  picture)  being  created. 

□   wContDefProc,  which,  if  nonzero,  contains  a  pointer  to  a 
routine  (definition  procedure,  or  defProc)  that  draws  the 
contents  of  the  window.  HodgePodge  stores  pointers  to  the 
routines  Paint  or  DispFontWindow  in  this  field. 
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Window  frames  and  controls 

There  are  two  kinds  of  predefined  window  frames,  document  and 
alert.  Figure  4-1  illustrates  them. 


Document  window  frame 

Figure  4-1 

Window  frames 


Alert  window  frame 


Some  of  the  standard  window 
parts  are  controls.  Controls  are 
described  in  more  detail  in  the 
following  section.  "Putting 
Controls  In  Windows." 


Clicking  refers  to  pressing  and 
releasing  the  mouse  button  while 
the  mouse  pointer  is  stationary  on 
the  screen. 


Dragging  refers  to  pressing 
the  mouse  button  to  select 
something  and  holding  the  button 
down  while  moving  the  mouse. 


The  alert  window  is  used  by  the  Dialog  Manager;  see 
"Constructing  Dialog  Boxes  and  Alerts,"  later  in  this  chapter.  The 
document  window  is  what  an  application  typically  uses.  Inside  a 
document  window  can  be  standard  window  parts,  which  include 
the  following: 

■  Title  bar,  a  rectangle  at  the  top  of  the  window  that  displays  the 
window's  title,  may  hold  the  close  and  zoom  boxes,  and  may 
be  a  drag  region  for  moving  the  window. 

■  Close  box  (go-away  box),  a  small  square  in  the  title  bar  that 
the  user  clicks  on  to  remove  the  window  from  the  screen. 

■  Zoom  box,  a  small  square  in  the  title  bar  that  the  user  clicks  on 
to  alternately  make  the  window  its  maximum  size  or  return  it  to 
its  previous  size  and  position. 

■  Right  scroll  bar,  a  rectangle  on  the  right  side  of  the  window  that 
the  user  manipulates  to  scroll  vertically  through  the  data  shown 
in  the  window. 

■  Bottom  scroll  bar,  a  rectangle  at  the  bottom  of  the  window  that 
the  user  manipulates  to  scroll  horizontally  through  the  data 
shown  in  the  window. 

■  Size  box,  a  small  square  at  the  lower-right  corner  of  the 
window  that  the  user  drags  to  change  the  size  of  the  window. 

■  Information  bar,  a  rectangular  area  where  the  application  can 
display  information  that  won't  be  affected  by  the  scroll  bars. 
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These  standard  parts  may  be  used  in  document  windows  only; 
they  may  not  be  added  to  alert  windows.  They  are  illustrated  in 
Figure  4-2. 
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Figure  4-2 

Standard  window  controls 


Color  In  an  application  should  be 
designed  carefully.  Please  refer 
to  Human  Interface  Guidelines: 
The  Apple  Desktop  Int  erf  ace  tor 
suggestions. 


It's  possible  to  define  your  own 
type  of  window,  such  as  round  or 
hexagonal.  See  the  Apple  IIGS 
Toolbox  Referenced  more 
Information. 


A  document  window  may  have  any  or  all  of  the  standard  window 
parts.  The  only  restrictions  are  that  if  there  is  a  close  or  zoom  box, 
there  must  also  be  a  tide  bar,  and  if  there  is  a  size  box,  there  must 
also  be  a  vertical  scroll  bar.  Common  sense  suggests  that  there  be 
a  zoom  box  if  there  is  a  size  box,  but  this  is  not  a  requirement. 

♦  Color:  You  can  specify  the  colors  of  the  frame  and  controls  of 
a  window  you  create.  Colors  are  selected  from  a  color  table. 
See  "Window  Manager"  in  the  Apple  IIGS  Toolbox  Reference 
for  details. 

You  can  use  the  standard  window  types,  or  you  can  create  your 
own  window  types.  Some  windows  may  be  created  indirectly  for 
you  when  you  use  other  parts  of  the  toolbox — for  example,  the 
Dialog  Manager  creates  a  window  to  display  an  alert.  Windows 
created  either  direcUy  or  indirectly  by  an  application  are 
collectively  called  application  windows.  There's  also  a  class  of 
windows  called  system  'windows;  those  are  the  windows  in 
which  desk  accessories  are  displayed. 
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A  region  is  a  graphic  object 
defined  by  QuickDraw  II.  See 
"Drawing  to  the  Screen"  in 
Chapter  3, 


The  routines  Paintlt  and  ShowFont 
in  Chapter  3  show  how 
HodgePodge  represents  the 
data  areas  of  its  windows. 


How  scrolling  is  accomplished  is 
described  later  In  this  section 
under  "Handling  Window- 
Related  Events." 


Content  region  and  data  area 

A  window  is  composed  of  regions.  The  window  as  a  whole  (the 
structure  region)  is  made  up  of  the  content  region  and  the  frame 
region: 

a  The  content  region  is  bounded  by  the  rectangle  you  specify 
when  you  create  the  window  (that  is,  the  port  rectangle  of  the 
window's  GrafPort).  The  content  region  is  where  your 
application  presents  information  to  the  user. 

□  The  frame  region  is  the  rest  of  the  window.  It  may  include 
several  subregions  that  correspond  to  the  locations  of  the 
standard  window  parts  described  earlier.  When  the  user 
manipulates  a  certain  control,  the  Window  Manager  sees  it  as 
an  event  occurring  in  a  certain  subregion.  See  "Handling 
Window-Related  Events,"  later  in  this  section. 

The  content  region  of  a  window  is  what  the  user  "sees"  within  the 
window.  It  commonly  represents  a  larger  area,  containing  more 
information  than  the  screen  can  display  at  one  time.  The  window 
is  then  like  a  microfiche  machine — what  is  seen  at  any  one  time 
in  its  content  region,  like  what  is  seen  in  a  microfiche  viewer, 
might  be  only  a  small  portion  of  the  window's  entire  data  area, 
equivalent  to  the  microfiche  sheet. 

The  data  area  is  a  pixel-based  "picture"  of  whatever  document  is 
being  displayed  in  the  window.  For  a  pixel  image  (such  as  a 
HodgePodge  picture  file),  the  data  area  is  the  pixel  image  itself.  I 
For  a  text  document  (such  as  a  HodgePodge  font  window  display), 
the  data  area  is  a  conceptual  representation  of  what  the  document 
would  look  like  if  it  were  a  pixel  image.  The  document  doesn't 
exist  in  that  form  anywhere;  the  appropriate  parts  of  it  are 
calculated  and  drawn  in  the  window's  GrafPort  each  time  the 
window  is  drawn  or  updated. 

Scroll  bars  are  the  controls  used  to  scroll  the  data  area  through 
the  content  region  of  the  window.  The  size  box  and  zoom  box  an 
used  to  display  more,  or  less,  of  the  data  area  at  one  time.  When 
the  window  as  a  whole  is  moved  to  another  location  on  the 
screen,  the  data  area  is  moved  with  it,  so  the  view  in  the  content 
region  remains  the  same. 
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Figure  4-3 

A  window  displays  part  of  its  data  area 


A  window's  plane  is  its  front-to- 
back  position  on  the  screen,  in 
relation  to  other  windows. 


Handling  window- related  events 

The  Window  Manager's  principal  function  is  to  keep  track  of 
overlapping  windows.  Your  application  can  draw  in  any  window 
without  running  over  onto  windows  in  front  of  it.  You  can  move 
windows  to  different  places  on  the  screen,  change  their  plane,  or 
change  their  size,  all  without  concern  for  how  the  various  windows 
overlap.  The  Window  Manager  keeps  track  of  any  newly  exposed 
areas  and  provides  a  convenient  mechanism  for  you  to  ensure 
that  they  are  properly  redrawn. 

There  are  two  ways  to  handle  user  input  in  relation  to  windows. 
You  can  poll  the  user  with  the  Event  Manager  routine 
GetNextEvent,  or  with  the  Window  Manager  routine  TaskMaster, 
which  handles  most  events  dealing  with  standard  user  interfaces. 
See  "Using  TaskMaster"  in  Chapter  3. 
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Compare  these  results  from 
FindWindow  with  the  TaskMaster 
task  codes  in  Table  3-3. 


If  you  are  using  GetNextEvent,  you  should  call  FindWindow  every 
time  a  mouse-down  event  occurs,  to  see  if  the  mouse  button  was 
pressed  inside  a  window.  The  FindWindow  call  determines  which 
region  is  affected,  and  returns  the  information  to  you.  The 
following  are  the  various  subregions  recognized  by  FindWindow, 
and  the  standard  actions  to  take  in  each  case. 

□  The  content  region  has  already  been  described.  If  the  mouse 
button  is  pressed  in  a  window's  content  region,  call 
SelectWindow  if  the  window  is  not  the  active  window.  Otherwise, 
handle  the  event  according  to  your  application. 

a  The  drag  area  corresponds  to  the  window's  tide  bar  (except  for 
the  close  and  zoom  boxes,  if  present).  Dragging  in  this 
subregion  pulls  an  outline  of  the  window  across  the  screen, 
moves  the  window  to  a  new  location,  and  makes  it  the  active 
window  (if  it  isn't  already). 

If  the  mouse  button  is  pressed  in  a  window's  drag  region,  call 
DragWindow. 

□  The  go-away  area  corresponds  to  the  close  box  in  the  windo 
title  bar.  Clicking  in  this  subregion  closes  the  window. 
Depending  on  your  application,  the  window  may  disappear 
permanently  or  simply  become  hidden. 

If  the  mouse  button  is  pressed  in  the  active  window's  close  bo: 
call  TrackGoAway.  If  TrackGoAway  returns  TRUE,  call 
Close  Window,  or  Hide  Window,  perhaps  after  saving  whatever 
the  user  was  working  on  inside  the  window.  You  may  also  want 
to  close  any  disk  file  associated  with  the  closed  window. 

n  The  zoom  area  corresponds  to  the  zoom  box  in  the  window's 
title  bar.  Clicking  in  this  subregion  toggles  between  the  curreni 
position  and  size,  to  a  maximum  size  and  back  again. 

If  the  mouse  button  is  pressed  in  the  active  window's  zoom 
area,  call  TrackZoom.  If  TrackZoom  returns  TRUE,  call 
ZoomWindow. 

□  The  grow  area  corresponds  to  the  size  box  in  the  window's 
lower-right  corner.  Dragging  in  this  region  pulls  the  lower-righ 
corner  of  an  outline  of  the  window  across  the  screen  with  the 
window's  origin  fixed,  and  then  resizes  the  window  when  the 
mouse  button  is  released. 

It  the  mouse  button  is  pressed  in  the  active  window's  grow  area, 
call  GrowWindow.   When  the  button  is  released,  call 
Size  Window. 
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□  The  menu  bar  is  not  a  window  subregion,  but  a  result  returned 
by  FindWindow  that  means  "not  on  the  desktop." 

If  the  mouse  button  is  pressed  somewhere  outside  the  desktop, 
it  is  most  likely  in  the  system  menu  bar.  Call  MenuSelect. 

♦  Inactive  window:  Clicking  in  any  region  (other  than  the  drag 
region)  of  an  inactive  window  should  have  no  effect  other  than 
making  it  the  active  window.  It  is  brought  to  the  front  and 
highlighted  to  indicate  that  it  is  active. 

♦  TaskMaster:  If  you  are  using  TaskMaster,  it  calls  FindWindow  for 
you.  It  also  calls  MenuSelect,  DragWindow,  TrackGoAway,  or 
other  appropriate  calls  depending  on  the  results  of 
FindWindow.  In  general,  you  needn't  handle  any  window- 
related  mouse  events,  except  possibly  in  the  content  region  of 
an  active  window.  TaskMaster  may  not  know  what  you  want 
drawn  in  an  active  window. 


The  visible  region's  the  portion  of 
a  window  that  is  not  offscreen  or 
hidden  by  other  windows.  It  is  one 
of  the  fields  in  a  GrafPort  that  clips 
drawing  commands.  See 
"Drawing  to  the  Screen"  in 
Chapter  3. 

The  update  region  is  the  portion  of 
a  window  that  needs  to  be 
redrawn.  It  may  be  a  part- 
exposed  by  moving  or  closing 
another  window,  or  it  may  be  a 
new  part  of  the  data  area 
exposed  during  scrolling. 


Drawing  or  redrawing  a  window 

When  a  window  is  drawn  or  redrawn,  the  window  frame  is  drawn 
first,  followed  by  the  window  contents.  The  Window  Manager 
handles  all  frame  drawing. 

When  a  window's  contents  need  to  be  redrawn,  the  Window 
Manager  generates  an  update  event  that  includes  a  pointer  to  the 
affected  window  in  the  message  field  of  the  event  record.  Your 
application  should  respond  to  update  events  as  follows: 

1.  Call  BeginUpdate.  This  procedure  temporarily  replaces  the 
visible  region  of  the  window's  GrafPort  with  the  intersection  of 
the  visible  region  and  the  update  region.  It  then  clears  (resets 
to  zero  size)  the  update  region  for  that  window. 

2.  Draw  the  window  contents.  Because  of  step  1,  the  redrawing  is 
automatically  clipped,  or  limited,  to  the  part  of  the  visible 
region  that  needs  updating. 

3.  Call  EndUpdate  to  restore  the  actual  visible  region. 

♦>  TaskMaster:  If  you  use  TaskMaster,  this  procedure  is  done  for 
you,  as  long  as  you  provide  TaskMaster  with  a  routine  that 
draws  your  window's  contents  (equivalent  to  step  2,  above). 
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♦  HodgePodge:  Although  it  uses  TaskMaster  and  doesn't  really 
need  an  update  routine,  HodgePodge  has  a  short  example  off  1 
an  update  routine  in  the  code  that  creates  one  of  its  dialog 
boxes.  See  the  listing  of  ShowPleaseWait,  under 
"Constructing  Dialogs  and  Alerts,"  later  in  this  chapter. 

Making  a  window  active 

A  number  of  Window  Manager  routines  change  the  state  of  a 
window  from  inactive  to  active  or  from  active  to  inactive.  For 
each  such  change,  the  Window  Manager  generates  an  activate 
event.  When  the  Event  Manager  finds  out  from  the  Window 
Manager  that  an  activate  event  has  been  generated,  it  passes  the!  J 
event  on  to  the  application  through  GetNextEvent. 

Activate  events  for  dialog  and  alert  windows  are  handled  by  the  1 1 
Dialog  Manager,  so  your  application  doesn't  have  to  bother  with 
them.  In  response  to  activate  events  for  windows  created  directlwl 
by  your  application,  you  might  take  actions  such  as  the  following: 

□  Inactivate  controls  in  inactive  windows,  and  activate  controls  in 
active  windows. 

□  In  a  window  that  contains  text  being  edited,  remove  the 
highlighting  or  blinking  cursor  from  the  text  when  the  window 
becomes  inactive,  and  restore  it  when  the  window  becomes 
active. 

□  Enable  or  disable  a  menu  or  certain  menu  items  as  appropriate 
to  match  what  the  user  can  do  when  windows  become  active  or 
inactive. 

♦  TaskMaster:  If  you  use  TaskMaster,  highlighting  of  standard 
windows  and  controls  is  handled  for  you.  Enabling  and 
disabling  of  menu  items  is  not. 

♦  HodgePodge:  To  keep  menu  highlighting  in  agreement  with 
activate  events,  HodgePodge  calls  its  subroutine  CheckFrontlj 
each  time  through  the  event  loop. 
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Local  coordinates  are  discussed 
under  "Drawing  to  the  Screen"  in 
Chapter  3. 


Your  application  determines  how 
many  pixels  are  needed  to  shift 
the  Image.  See  "Putting  Controls 
In  Windows,"  later  in  this  chapter. 


Scrolling 

Scrolling  is  the  process  by  which  the  user  can  bring  different  parts 
of  a  document  (data  area)  into  view  in  a  window.  To  accomplish 
scrolling,  the  user  manipulates  scroll  bars,  standard  window 
controls  managed  by  the  Control  Manager.  An  application  (or 
TaskMaster)  responds  to  user  manipulation  of  scroll  bars  by: 

1.  Updating  the  appearance  of  the  scroll  bars  to  reflect  the 
change  in  position  of  the  data  area.  This  step  is  described 
under  "Putting  Controls  in  Windows,"  later  in  this  chapter. 

2.  Showing  a  new  part  of  the  document  in  the  window.  The 
application  (or  TaskMaster)  does  this  by  shifting  the  image  in 
the  window,  then  changing  the  window's  local  coordinates  and 
redrawing  the  parts  of  the  data  area  brought  into  view.  This  step 
is  described  below. 

♦  TaskMaster:  If  your  application  uses  TaskMaster,  it  can  have 
TaskMaster-controlled  scroll  bars  (frame  scroll  bars)  in  its 
windows.  In  that  case  the  application  need  have  no  scrolling 
routines  at  all.  The  following  applies  only  if  your  application 
creates  and  manipulates  its  own  scroll  brars. 

♦  HodgePodge:  Because  it  calls  TaskMaster,  HodgePodge  has  no 
scrolling  procedure. 

Consider  a  pixel  image,  part  of  which  is  displayed  in  a  window, 
such  as  the  dollar  bill  in  Figures  3-5  and  3-6.  Let's  say  that  the 
window  presently  shows  George  Washington's  face  (Figure  4-4), 
and  the  user  wants  to  scroll  the  image  to  bring  into  view  the 
circular  Federal  Reserve  seal  to  the  left  of  Washington.  With  the 
mouse,  the  user  activates  the  left-facing  arrow  on  the  bottom 
scroll  bar.  When  your  application  determines  that  there  has  been 
a  mouse-down  event  in  that  part  of  the  scroll  bar,  it  should 
respond  as  follows: 

1.  Call  the  QuickDraw  routine  ScrollRect  and  tell  it  to  move  all 
the  pixels  in  the  content  area  of  the  window  a  certain  number 
of  pixels  to  the  right.  George  shifts  a  bit  to  the  right.  The  way 
ScrollRect  works,  any  pixels  moved  off  the  right  edge  of  the 
window  are  lost,  and  extra  pixels  added  to  the  left  edge  of  the 
image  are  blank  (colored  with  the  background  pattern). 

2.  Your  onscreen  image  has  been  shifted,  but  QuickDraw  hasn't 
automatically  filled  in  the  new  part  of  the  image  that  has  come 
into  view.  However,  ScrollRect  returns  information  to  you  that 
tells  you  exactly  what  part  of  your  window  needs  redrawing.  Call 
InvalRgn  to  add  that  newly  exposed  area  to  the  window's 
update  region. 
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See  the  toolbox  reference  for 
instructions  on  installing  a  control 
action  procedure. 


3.  Call  BeginUpdate. 

4.  Call  your  routine  that  draws  window  contents.  What  that  routine 
should  do  is: 


;  last 


a.  Set  the  local  origin  to  its  scrolled  value:  what  it  was  the  last 
time  the  window's  contents  were  drawn  PLUS  the  (negative 
value  of  the)  number  of  pixels  that  ScrollRect  shifted  the 
image. 

b.  Draw  the  window's  contents  (perhaps  by  calling  PPToPort). 
The  image  is  properly  shifted  and  clipped  so  that  just  the 
needed  part  is  drawn.  There's  the  seal! 

c.  Set  the  local  origin  back  to  (0,0). 
5.  Call  EndUpdate. 

If  you  put  the  above  steps  into  a  control  action  procedure,  they 
will  be  called  repeatedly  as  long  as  the  user  holds  the  mouse 
button  down  with  the  pointer  in  the  scroll  bar.  The  image  will 
scroll  continuously. 

Alternatively,  if  continuous  scrolling  is  unnecessary,  you  can 
ignore  steps  3  through  5.  The  InvalRgn  call  causes  the  Window 
Manager  to  generate  an  update  event  for  exactly  that  part  of  the 
window,  and  the  next  time  through  the  event  loop,  your  regular 
update  routine  redraws  the  window.  The  redrawing  won't  happen, 
though,  until  the  user  releases  the  mouse  button. 
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a.  Part  of  a  document  displayed 
in  a  GrafPort 
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b.  Application  scrolls  image  to 
the  right.  Pixels  moving  off  right 
edge  are  lost;  new  area  filled 
with  background  pixels. 
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c.  Application  updates  the  new 
area  scrolled  into  view  by  shifting 
coordinates  and  redrawing. 

Figure  4-4 

Scrolling  a  pixel  image  in  a  window 
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Important     When  a  window  is  created,  the  Window  Manager  assigns  its  port 
rectangle  origin  a  value  of  (0,0)  In  local  coordinates.  Whenever  It 
redraws  the  window  frame,  the  Window  Manager  requires  the  origin 
to  have  that  same  value. 


Therefore,  every  time  you  draw  your  window's  contents  you  should 
(1)  set  the  origin  to  whatever  is  appropriate,  (2)  draw  the  conti 
and  then  (3)  restore  the  origin  to  (0,0). 


The  sequence  of  subroutine  calls 
described  In  this  section  is 
diagrammed  in  Appendix  D. 


DoOpenltem  is  in  the  source  file 
MENU.PAS. 


~l 


Opening  a  window:  an  example 

The  following  example  from  HodgePodge  shows  the  steps 
involved  in  allocating  the  memory  for,  creating,  and  drawing  the 
initial  contents  of  a  window.  Remember  that  in  HodgePodge  there 
are  two  types  of  window:  one  type  displays  picture  files  and  the 
other  displays  lines  of  text  using  a  particular  font. 


The  sequence  starts  when  the  user  chooses  Open  from  the  File 
menu  or  Show  Font  from  the  Font  menu.  In  either  case  execution 
passes  from  DoMenu  to  the  routine  DoOpenltem.  DoOpenltem  is 
very  short: 


procedure  DoOpenltem; 

begin 

if  wlndex  <  LastWind  then 
if  Open Window  then 

AddtoMenu 
else 
else 

ManyWindDialog; 
end; 


(begin  DoOpenltem...} 


{If  there's  room  for  another  window...} 
{call  OpenWindow.  If  it  opens  OK..} 
{...add  its  name  to  the  Windows  menu} 

{If  16  windows  already  open...} 

{put  up  a  dialog  and  disallow  open} 

{End  of  DoOpenltem} 

Note  that  DoOpenltem  calls  both  OpenWindow  (to  open  the 
window)  and  AddToMenu  (to  add  the  window's  name  to  the 
Windows  menu).  AddToMenu  is  described  under  "Making  and 
Modifying  Menus"  in  Chapter  5.  If  16  windows  are  already  open, 
HodgePodge  does  not  allow  another  to  be  opened. 
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OpenWindow  Is  in  the  source  file 
WINDOW. PAS. 


OpenWindow  determines  which  type  of  window  is  to  be  opened, 
and  prompts  the  user  for  the  necessary  information  (picture 
filename  or  font  characteristics).  It  then  calls  the  routine 
DoTheOpen,  which  actually  opens  the  window.  OpenWindow  looks 
like  this: 


function     OpenWindow:    Boolean; 

begin 

OpenWindow    :=  FALSE; 

if   (LoWord (Event .wmTaskData   =FontItem)    then 
begin 
if  DoChooseFont   then 
if  DoTheOpen   then 
OpenWindow    :=  TRUE 
end 
else 
begin 
if  AskUser  then 
if  DoTheOpen   then 
OpenWindow    :=  TRUE 
end; 


end; 


{begin  OpenWindow...} 


{initial  value  of  function  =  FALSE} 
{if  it  is  a  font  window...} 

{...and  if  the  user  doesn't -cancel...} 
{...and  if  the  window  opens  OK...} 
{OpenWindow  completes  successfully} 

{if  it  is  a  picture  window...} 

{...and  if  the  user  doesn't  cancel...} 
{...and  if  the  window  opens  OK...} 
{OpenWindow  completes  successfully} 


{End  of  OpenWindow} 


DoTheOpen  is  in  the  source  file 
WINDOW.PAS. 


The  complete  format  for  the 
NewWindow  parameter  list  is 
given  under  "Window  Manager" 
in  the  Apple  IIGS  Toolbox 
Reference 


DoChooseFont  was  described  earlier  in  this  chapter.  AskUser  is 
described  in  Chapter  5,  under  "Communicating  With  Files  and 
Devices." 

Once  it  has  all  the  information  it  needs,  OpenWindow  calls 
DoTheOpen  to  open  the  window.  DoTheOpen  looks  like  a  long 
and  complex  routine,  but  that's  partly  because  it  is  two  routines  in 
one;  it  handles  two  types  of  windows.  It  also  does  a  lot  of 
assignment  and  initialization  that  your  programs  may  not  need  at 
this  point.  We'll  break  its  description  into  chunks  to  make  it  easier 
to  follow. 

DoTheOpen  starts  by  allocating  memory  for  the  window  data 
record  (a  structure  defined  by  HodgePodge),  and  putting  some 
initial  values  into  the  NewWindow  parameter  list,  a  toolbox- 
defined  structure  that  is  a  required  input  to  the  NewWindow  call. 


function   DoTheOpen  :  Boolean; 

war    theWindow    :  GrafPortPtr; 
myDataHandle :  WindDataH; 

theMenuStr   :  Str255; 
ourFontlnfo  :  FontlnfoRec; 


{begin  DoTheOpen...} 

{a  pointer  to  our  window} 
{a  handle  to  our  own  window-data 
record — defined  in  GLOBALS.PAS} 
{window's  title  for  menu  display} 
{to  hold  font  information} 
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DoTheOpen  :=  FALSE; 

myDataHandle  : = 

tfindDataH ( 

NowHandla  (sizeof (WindDataRec)  , 

myMemorylD, 

attrLocked+att  rFixed , 

Ptr(O))); 

if   isToolError  then 

Exit; 

with   myWind  do 

begin 

paramLength 

:=  sizeof (ParamList) ; 

wFrameBits 

:=  $DDA0; 

wRefCon 

:-  Longlnt (myDataHandle) ; 

SetRect (wZoor 

1,0,26,520,190); 

wColor 

:=  NIL; 

wYOrigin 

:=  0; 

wXOrigin 

:=  0; 

wDataH 

:=  188; 

wDataW 

=  640; 

wMaxH 

-  200; 

wMaxW 

=  640; 

wScrollVer 

=  4; 

wScrollHor 

=  16; 

wPageVer 

=  40; 

wPageHor 

>=  160; 

wlnfoRefCon 

=  0; 

wlnfoHeight 

=  0; 

wFrameDefProc 

=  NIL; 

wlnfoDefProc 

=  NIL; 

wPlane 

=  -l; 

wStorage 

=  NIL; 

end; 

theMenuStr  :=  cor 

icat  ('==', 

myReply . filename , 

•\N\ 

IntToString ( 

FirstWindltem+wIndex) , 

'\0.'); 

with   myDataHandle 

AA  do 

begin 

name    : =  myF 

eply. filename; 

menuStr  :=  the 

MenuStr; 

menuID   :=  Fir 

stWindltem+wIndex; 

end; 

{initial  value  of  function  =  FALSE} 

{get  a  handle  to  our  record  by...) 
{...requesting  memory  with  these...} 
{attributes:   size,  User  ID,} 
{ locked  and  fixed, } 
{anywhere} 

{terminate  if  memory  unavailable} 

{myWind  is  a  window  parameter  block,} 

{...required  input  to  NewWindow  call} 

{Initialize  the  window's  features:} 

{total  size  of  list} 

{this  specifies  scroll  bars,  etc.} 

{handle  to  our  window  data  record} 

{window  size  &  postion  when  zoomed} 

{no  colors  for  this  window} 

{y-coord.  of  port  rect  origin} 

{x-coord.  of  port  rect  origin} 

{document  height} 

{document  width} 

{max.  window  height  to  grow} 

{max.  window  width  to  grow} 

{amt.  to  scroll  if  v.  arrow  clicked) 

{amt.  to  scroll  if  h.  arrow  clicked) 

{amt.  to  scroll  if  v.  page  clicked) 

{amt.  to  scroll  if  h.  page  clicked) 

{no  info,  bar  for  this  window} 

{no  info  bar  for  this  window} 

{no  special  frame-drawing  routine} 

{no  special  info-bar  content  routine} 

{make  this  window  frontmost} 

{let  Window  Mgr  allocate  the  memory} 


{Make  a  title  for  the...} 
{...window  to  appear  in...} 

{...theWindows  menu.} 

{In  the  window-data  record..} 

{...fill  in  the  name  field} 
{...fill  in  the  menu  title  field} 
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After  this  initial  allocation,  DoTheOpen  sets  up  the  window  to 
display  either  text  or  a  picture.  It  inserts  into  the  NewWindow 
parameter  list  a  pointer  to  the  procedure  that  draws  the  window's 
interior,  and  sets  the  remaining  fields  in  the  window-data  record. 


=  DesiredFont; 
=  isMonoFont; 


if  LoWord (Event. wmTaskData)    =  Fontltem  then 
begin 
myWind.wContDefProc    :=  @DispFontWindow; 
with  myDataHandle"*    do 
begin 
flag         :-  1; 
theFont 
isMono 
end; 
InstallFont (desiredFont, 0) ; 
GetFontlnfo(ourFontlnfo) ; 
myWind.wDataH    :=  15* (ourFontlnfo. ascent + 
ourFontlnfo. descent) ; 

end 

else 
begin 
myWind.wContDefProc  :=  SPaint; 
with   myDataHandleAA  do 
begin 
flag  :=  0; 
pict  :=  picHndl; 
end; 
end; 


{if  it  is  a  font  window...} 
{DispFontWindow  will  draw  contents} 

{1  means  it's  a  font  window} 
{store  present  font  ID  in  theFont} 
{store  present  setting  of  isMonoFont} 

{load  the  desired  font  into  memory} 
{...get  its  characteristics...} 
{...and  calculate  document  height — } 
{15  =  2  +  no.  of  lines  in  document} 
{end  of  IF  it's  a  font  window} 

{But  if  it's  a  picture  window...} 

{Paint  will  draw  contents} 


{0  means  it's  a  picture  window} 
{store  handle  to  desired  picture...} 
{...(determined  by  AskUser)  } 
{end  of  IF  it's  a  picture  window} 


Now  DoTheOpen  determines  where  on  the  screen  the  window  is  to 
appear.  Each  newly-opened  window  is  offset  down  and  to  the  right 
from  the  previously  opened  window.  Recall  from  SetUpWindows 
(Chapter  2)  that  iSizPos  is  the  initial  position  and  size  of  a 
window. 


with  myWind  do 
begin 
wTitle  :=  @myDataHandleAA .name; 
SetRect (wPosition, 

wXoffset  +  iSizPos.hl, 
wYoffset  +  iSizPos.vl, 
wXoffset  +  iSizPos.h2, 
wYoffset  +  iSizPos.v2); 
end; 

wXoffset  :=  wXoffset  +20; 
wYoffset  :=  wYoffset  +  12; 
if  wYoffset  >  120  then 
wYoffset  :=  12; 


{In  the  window-data  record..} 
{set  window  title  to  name  field} 

{Add  the  window  dimensions  to  the...} 
{...current  X-  and  Y-  offsets} 

{end  of  setting  record  fields} 

{Then  increment  offsets...} 

{...to  set  position  of  next  window} 

{ (after  10  windows  make  another  row) } 
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Sn '  T^f  ^  6Verythin«  is  a11  set  "P>  DoTheOpen  creates  to 
window  itself,   t  uses  the  NewWindow  call,  passing  to  NewWindow 

he  S  r    ^    !!     f  DoThe°Pen  J«t  filled  in.  You  can  see  from 
he  fol  owing  code  that  opening  a  window  is  quite  simple  and 

short.  It  is  the  preparation  and  initialization  that  makes  the 

routine  seem  long  and  complicated. 


end: 


theWindow  :=  NewWindow  (myWind)  ; 

SetPort  (theWindow)  ; 
SetOriginMaaJc  ($FFFE,  theWindow)  ; 

InitCursor; 

DoTheOpen  :=  TRUE; 


{Open  the  window — NewWindow 
returns  a  pointer  to  it} 
{Make  the  window  the  active  port} 
{Adjust  window  origins  to  make 
dithered  colors  come  out  right} 
{Go  back  to  the  arrow  cursor} 
{DoTheOpen  completes  successfully} 
{End  of  DoTheOpen} 


Putting  controls  in  windows 

A  control  is  an  object  on  the  IIGS  screen  with  which  the  user 
using  the  mouse,  can  cause  instant  action  with  graphic  results  or 
change  settings  to  modify  a  future  action.  Controls  are  T 

fundamental  to  the  concepts  behind  the  Human  Interface 
Guidelines;  they  provide  a  simple,  intuitive  interface,  permitting 
he  user  to  affect  the  course  of  an  application.  If  welWesigned 
they ^reinforce  the  feelings  of  user  control,  friendliness,  and    ' 
consistency  that  mark  a  good  desktop  application 


The  control  Manager  is  the  part  of  the  Apple  IIGS  Toolbox  that 

ca  SsZtre^6!",'  manJPUlate  COntr0lS'  The  Control  MaC 
wheTe5,  an"  how""1  °Peratl°nS'  **  *  "P  *  *»  »  ***  H 

a^ranoe'onV5  Vari°US  T*'  ^  ^  itS  °Wn  characteristic 
S!,v   T        lh?uSCreen  and  responses  to  the  mouse.  Each 
ndividual  control  has  its  own  specific  properties-such  as  its 
location,  size,  and  setting-but  controls  of  the  same  type  behave 
in  the  same  general  way.  YP^  e 


Types  of  controls 

Certain  standard  types  of  controls  are  predefined  for  you  Your 

S I  c°onntrolsepi,yHUrSe  *?**  ^^  ***»•  °r  deL  its  own 
funSons  Redefined  controls  perform  a  number  of 


Chapter  4:  Using  the  Toolbox  (II) 


■  Buttons  cause  an  immediate  or  continuous  action  when  clicked 
or  pressed  with  the  mouse.  They  typically  appear  on  the  screen 
as  rounded-corner  rectangles  with  a  title  centered  inside. 

■  Check  boxes  retain  and  display  a  setting,  either  checked  Con) 
or  unchecked  (off);  clicking  with  the  mouse  reverses  the  setting. 
On  the  screen,  a  check  box  appears  as  a  small  square  with  a 
title  to  the  right  of  it;  the  box  is  either  filled  in  with  an  X 
(checked)  or  empty  (unchecked).  Check  boxes  are  frequently 
used  to  control  or  modify  some  future  action,  instead  of 
causing  an  immediate  action  of  their  own.  More  than  one  box 
may  be  checked  at  any  one  time. 

■  Radio  buttons  also  retain  and  display  an  on-or-off  setting. 
They're  organized  into  families;  only  one  button  in  a  family 
should  be  on  at  a  time.  Clicking  any  button  on  should  turn  off 
all  the  others  in  the  family,  like  the  buttons  on  a  car  radio.  The 
radio  button  that's  on  is  filled  with  a  small  black  circle. 

■  Dials  display  a  quantitative  setting  or  value,  typically  in  some 
pseudo-analog  form  such  as  the  position  of  a  sliding  switch,  the 
reading  on  a  thermometer  scale,  or  the  angle  of  a  needle  on  a 
gauge.  The  setting  may  be  displayed  numerically  as  well. 

The  control's  moving  part  that  displays  the  current  setting  is 
called  the  indicator.  The  user  may  be  able  to  change  a  dial's 
setting  by  dragging  its  indicator  with  the  mouse,  or  the  dial 
may  simply  display  a  value  not  under  the  user's  direct  control 
(such  as  the  amount  of  free  space  remaining  on  a  disk). 

The  standard  controls  and  a  few  other  typical  controls  are 
illustrated  in  Figure  4-5. 


Button  1 


Button  2 


H  Check  box  1 
[J  Check  box  2 
□  Check  box  3 

O  Radio  button  1 
C«  Radio  button  2 
O  Radio  button  3 


Figure  4-5 

Standard  and  typical  controls 
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>  Dials 


OiNil         1^E> 
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Scroll  bars 

Scroll  bars  are  predefined  dials.  Selecting  the  arrows  in  a  scroll 
bar  scrolls  data  a  line  at  a  time  Cor  an  analogous  number  of  pixels 
in  the  horizontal  direction);  selecting  the  paging  regions  scrolls 
data  a  page  at  a  time;  and  dragging  the  thumb  to  any  position 
within  the  scrolling  area  locates  the  window  equivalently  within 
the  data  area.  Although  each  of  these  components  may  seem  to 
behave  like  individual  controls,  they  are  all  parts  of  a  single 
control,  the  scroll-bar  type  of  dial.  You  can  define  other  dials  of 
any  shape  or  complexity  if  your  application  needs  them. 

♦  Note:  For  scrolling,  what  constitutes  a  page  and  what  constitutes 
a  line  are  definable  by  your  application. 

Figure  4-6  shows  the  parts  of  the  vertical  and  horizontal  scroll  ba 


Up  arrow  - 


u 


Page-up  region  ■ 
Thumb  — 


Page-down  region 


Down  arrow  — 

I 


O 


O 


Figure  4-6 

Parts  of  the  scroll  bars 

Scroll  bars  are  proportional — that  is,  they  show  the  relationship 
between  the  total  amount  of  data  and  the  amount  viewed  (and 
where  the  view  is  in  the  data).  As  Figure  4-7  shows,  the  thumb  is  I 
the  same  ratio  to  the  scrolling  area  (the  total  distance  between  the 
arrows)  as  the  content  region  is  to  the  data  area. 
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When  the  user  clicks  in  a  scroll  bar,  the  Control  Manager  returns 
to  your  application  a  part  code,  telling  it  what  part  of  the  scroll 
bar  the  event  occurred  in.  Depending  on  whether  it  is  in  an  arrow, 
paging  region,  or  thumb,  your  application  probably  should  scroll 
the  document  by  a  different  amount.  Once  you  know  how  much 
the  view  should  be  scrolled,  you  can  recalculate  the  scroll  bar 
values  to  keep  the  proportions  as  illustrated  in  Figure  4-7.  Then, 
call  SetCtlValue  to  redraw  the  scroll  bar  with  the  thumb  in  the 
proper  new  position. 

♦  Note:  Part  codes  are  returned  for  all  types  of  controls,  but  they 
are  most  significant  for  complex  controls  such  as  scroll  bars. 

With  the  SetCtlParams  call,  you  can  store  in  a  scroll  bar's  record 
the  current  sizes  of  your  document's  data  area  and  content  region 
(window  size).  Then  you  can  easily  calculate  their  proportions  for 
setting  scroll  bar  values  after  scrolling  or  resizing. 


Figure  4-7 

Relation  of  scroll  bars  to  data  area 
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Highlighting  can  mean  different 
mings  in  different  instances,  but  it 
often  consists  of  inverting  an 
object-that  is.  changing  all  its 
black  pixels  to  white,  and  vice 
versa  . 


Active  controls  and  highlighting 

If  the  user  presses  the  mouse  button  when  the  cursor  is  over  a 
control,  the  control  is  usually  highlighted;  see  Figure  4-8.  It's 
also  possible  for  just  part  of  a  control  to  be  highlighted-  for 
example,  if  the  user  presses  the  mouse  button  when  the  pointer  is 

^ShShtedSCr011  ^  ^  3rrOW'  ~  ^  "**  ™*  * 

A  control  may  be  active  or  inactive.  Active  controls  respond  to 
the  users  mouse  actions;  inactive  controls  don't.  A  control  should 
be  made  inactive  when  it  has  no  meaning  or  effect  in  the  curreT 
context  such  as  an  Open  button  when  no  document  has  been 

c  oil  in   a  °Pen'  °r  "  SCr°n  bar  WhCn  there'S  currentJy  "Othing  to 
scroll  to.  An  mactive  control  is  shown  in  some  special  way 

anTinf  ?  °n  '^  Tr01  type-  FigUre  4"8  illustrates  some  active 
and  inactive  controls. 


■<m 


Button 


Q^  Check  box 
Q  Radio  button 


Button 


□  Check  box 
O  Radio  button 
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Active  (high  lighted) 
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Button 


i  Check  oox 
O  Radio  button 
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Inactive 


Figure  4-8 

Active  controls  and  inactive  controls 

-The  title  and  outline  of  a  button,  check  box,  or  radio  button  are 
dimmed  automatically  when  the  control  is  made  inacto   S^L 
4-jBshows  two  different  appearances  that  an  inactive  Z"uZ- 

You  can  make  a  control  inactive  by  setting  its  value  to  a  carting 
number.  You  can  also  render  a  control  inactive  bTmak^  , 

cr  bt:^ controls  are  — e  - *e  «^X 
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Using  controls 


Controls  and  windows 

Every  control  belongs  to  a  window:  when  the  control  is  displayed, 
it  appears  within  that  window's  content  region;  when  manipulated 
with  the  mouse,  it  acts  on  that  window.  All  coordinates  pertaining 
to  the  control  (such  as  those  describing  its  location)  are  given  in 
the  window's  local  coordinate  system.  Even  the  state  of  the 
control  can  be  tied  to  the  state  of  the  window.  A  bit  in  the 
window's  record  can  be  set  so  the  controls  in  the  window  will  be 
considered  inactive  if  the  the  window  is  inactive.  See  "Window 
Manager"  in  the  Apple  IIGS  Toolbox  Reference. 

♦  Frame  scroll  bars:  Frame  scroll  bars  (manipulated  by 
TaskMaster)  work  the  same  as  other  controls,  but  are  part  of  a 
window's  frame  region  rather  than  its  content  region. 

Controls  and  events 

When  GetNextEvent  reports  that  an  update  event  has  occurred  for  a 
window,  your  application  should  call  DrawControls  to  redraw  the 
window's  controls  as  part  of  the  process  of  updating  the  window. 

♦  TaskMaster:  If  you're  using  TaskMaster,  you  needn't  redraw 
controls  that  are  part  of  the  window  frame — TaskMaster  takes 
care  of  it  for  you. 

When  GetNextEvent  reports  a  mouse-down  event  for  a  window 
that  contains  controls,  do  this: 

1.  Call  FindWindow  to  determine  which  part  of  which  window  the 
cursor  was  in  when  the  user  pressed  the  mouse  button.  If  it  was 
in  the  content  region  of  the  active  window,  continue  with  step  2. 

2.  Call  FindControl  to  find  out  where  the  event  occurred. 

3.  If  FindControl  indicates  that  the  event  occurred  in  an  active 
control,  call  TrackControl  to  handle  user  interaction  with  the 
control.  TrackControl  handles  the  highlighting  of  the  control 
and  determines  whether  the  mouse  is  still  in  the  control  when 
the  mouse  button  is  released.  The  routine  also  handles  the 
dragging  of  the  thumb  in  *a  scroll  bar  and  responds  to  presses 
or  clicks  in  the  other  parts  of  a  scroll  bar. 
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4.  If  TrackControl  confirms  that  a  valid  control  was  selected,  do] 
whatever  is  appropriate  as  a  response.  (If  no  control  was  ' 
selected,  then  of  course  no  action  is  necessary). 

The  application's  exact  response  to  mouse  activity  in  a  control 
that  retains  a  setting  depends  upon  the  current  setting  of  the 
control.  For  example,  when  a  check  box  or  radio  button  is  clicke 
you'll  make  a  Control  Manager  call  to  change  the  setting  and 
draw  or  clear  the  mark  inside  the  control. 

♦  TaskMaster:  If  your  application  calls  TaskMaster,  the  above 
procedure  is  handled  automatically  for  frame  scroll  bars  in 
standard  windows.  Only  if  you  have  other  controls  will  you 
need  a  control-drawing  routine. 

♦  HodgePodge:  Because  it  uses  only  window-frame  controls,  and 
because  it  calls  TaskMaster,  HodgePodge  has  no  specific 
routine  to  manipulate  or  draw  controls. 

Defining  your  own  controls 

In  addition  to  predefined  controls,  you  can  also  define  your  cw... 
custom  controls.  Perhaps  you  need  a  three-way  selector  switch,  at 
memory-space  indicator  that  looks  like  a  thermometer,  a  thruster 
control  for  a  spacecraft  simulator,  or  some  other  special  type  of 1 
control.  Controls  and  their  indicators  may  occupy  regions  of  any 
shape. 

To  define  your  own  type  of  control,  you  place  a  control  definitiol 
procedure  in  your  application.  The  Control  Manager  stores  the 
address  of  the  procedure  in  the  ctlProc  field  of  the  control  record 
when  you  create  the  control  with  a  NewControl  routine.  Later, 
when  the  Control  Manager  needs  to  perform  a  type-dependent 
action  on  the  control,  it  calls  the  control  definition  procedure 
See  the  Apple  IIGS  Toolbox  Reference  for  details. 
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Manipulating  lists  of  selectable  items 

If  your  program  displays  a  list  of  available  fonts,  files,  telephone 
numbers,  icons,  or  other  items  in  a  window,  it  may  put  them  in 
lists,  as  defined  by  the  Apple  IIGS  Toolbox.  A  list  is  a  vertical 
arrangement  of  similar  items  on  the  screen,  with  a  scroll  bar  to 
the  right.  Each  item  in  the  list  is  selectable,  meaning  it  can  be 
highlighted  individually,  with  a  mouse  click  or  other  action. 
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The  List  Manager  is  the  Apple  IIGS  tool  set  that  creates,  manipu- 
lates and  supports  lists.  It  relieves  you  (the  programmer)  of  much 
of  the  housekeeping  involved  with  building  and  maintaining 
complicated  lists  of  items  the  user  may  select  from.  Lists  created 
by  the  List  Manager  are  custom  controls,  called  list  controls;  that's 
why  we  mention  the  List  Manager  here,  under  the  Control 
Manager. 

You  create  a  list  as  a  list  record,  with  a  specific  format.  You  may 
use  the  List  Manager  to  sort  the  list,  if  desired,  and  then  to  create 
the  list  control.  Once  the  list  control  is  drawn  on  the  screen,  the 
user  can  select  individual  items  or  a  range  of  items  from  the  list. 
How  your  application  handles  those  selections  is,  of  course,  up  to 
you. 


Constructing  dialog  boxes  and  alerts 

Two  of  the  most  useful  and  versatile  means  of  commmunicating 
with  your  application's  user  are  provided  by  dialog  boxes  and 
alerts.  The  Dialog  Manager  provides  these  capabilities  in  a  way 
consistent  with  the  Apple  Human  Interface  Guidelines. 

The  Dialog  Manager  is  a  sophisticated  window-  and  control- 
manipulation  tool  set.  It  automatically  performs  many  functions 
your  application  would  otherwise  have  to  manage  explicitiy 
through  Event  Manager,  QuickDraw  II,  Window  Manager,  LineEdit, 
and  Control  Manager  calls. 


What  are  dialog  boxes? 

Your  application  typically  puts  a  dialog  box  on  the  screen  when  it 
needs  more  information  from  the  user  in  order  to  carry  out  a 
command.  As  shown  in  Figure  4-9,  a  dialog  box  resembles  a  form 
on  which  the  user  checks  boxes  and  fills  in  blanks. 
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Figure  4-9 

A  modal  dialog  box 

By  convention,  a  dialog  box  appears  slightly  below  the  menu  bar 
is  somewhat  narrower  than  the  screen,  and  is  centered  between   ' 

foUow^n  86S  °f  thS  SCrCen-  U  may  COntain  ^  of 

□  informative  or  instructional  text 

□  rectangles  in  which  text  may  be  entered  (initially  blank  or 
containing  default  text  that  can  be  edited) 

□  controls  of  any  kind 

□  graphics  (icons  or  QuickDraw  II  pictures) 

□  anything  else  your  application  wants 

The  user  provides  the  necessary  information  in  the  dialog  box 
for  example  by  entering  text  or  clicking  a  check  box.  There's    ' 
usually  a  button  labeled  OK  to  tell  the  application  to  accept  the 
-formation  provided  and  perform  the  command,  and  a  button 

btnt-     aTl  t0  CanCd  thG  C°mmand  3S  thou*h  *  h*d  ^ve 
been  given  (retractmg  all  actions  since  its  invocation).  Some 

dialog  boxes  may  use  a  more  descriptive  word  than  OK  for 

simplicity,  we'll  refer  to  the  button  as  the  OK  button.  There  may 

elch  in  Z7  °ne  bUU°n  that  Wil1  Perform  *e  c°™< 

eacn  in  a  different  way. 
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Modal  or  modeless 

Most  dialog  boxes  require  the  user  to  respond  before  doing 
anything  else.  Clicking  a  button  to  perform  or  cancel  the  command 
makes  the  box  go  away;  clicking  outside  the  dialog  box  only  causes  a 
beep  from  the  speaker.  This  type  of  box  is  called  a  modal  dialog 
box  because  it  puts  the  user  in  the  state  Cor  mode)  of  being  able  to 
work  only  inside  the  dialog  box.  Figure  4-9  is  an  example  of  how  a 
modal  dialog  box  might  look;  note  that  it  has  no  close  box. 

One  of  the  buttons  in  a  modal  dialog  box  may  be  boldly  outlined;  it 
is  called  the  OK  button  (whatever  text  it  may  contain).  Pressing  the 
Return  key  has  the  same  effect  as  clicking  the  OK  button;  it  should 
initiate  the  preferred  (or  safest)  action  in  the  current  situation.  If 
there's  no  boldly  outlined  button,  pressing  the  Return  key  has  no 
effect.  A  Cancel  button,  if  present,  closes  the  dialog  box  and  cancels 
the  effects  of  all  work  done  while  the  box  was  open. 

Other  dialog  boxes  do  not  require  the  user  to  respond  before 
doing  anything  else.  They  are  called  modeless  dialog  boxes.  The 
user  can  work  in  a  document  window  on  the  desktop  between 
clicking  buttons  in  a  modeless  dialog  box.  Modeless  dialog  boxes 
can  be  set  up  to  respond  to  the  standard  editing  commands  in 
the  Edit  menu.  Clicking  a  button  in  a  modeless  dialog  box  does 
not  make  the  box  go  away;  it  stays  on  the  desktop  so  that  the  user 
can  perform  the  command  again. 

As  shown  in  Figure  4-10,  a  modeless  dialog  box  typically  looks  like 
a  document  window.  It  can  be  moved,  made  inactive  and  active 
again,  or  closed  like  any  document  window.  When  you're  finished 
with  the  command  and  want  the  box  to  go  away,  you  can  click  its 
close  box,  or  you  can  choose  Close  from  the  File  menu  if  the 
dialog  box  is  the  active  window. 


=n                   Chnnge                 -Mlg 

Find  text:    Guide  Lines 

Change  to:   Guide  lines 

Change  next         [Change  All 

Figure  4-10 

A  modeless  dialog  box 
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Update  routines  are  described 
under  "Creating  Windows," 
earlier  in  this  chapter 

ShowPleaseWait  and 
HidePleaseWait  are  in  the  source 
file  DIALOG.PAS. 


Some  dialog  boxes  may  in  fact  require  no  response  at  all.  Foj 
example,  while  an  application  is  performing  a  time-consuming 
process,  it  can  display  a  dialog  box  that  contains  only  a  message 
telling  what  it's  doing;  then,  when  the  process  is  complete,  the 
application  can  simply  remove  the  dialog  box.  HodgePodge  does 
this  with  the  ShowPleaseWait  and  HidePleaseWait  routines 
called  up  during  tool  initialization.  ShowPleaseWait  also 
demonstrates  how  to  bring  up  a  dialog  box  and  show  it 
immediately,  without  even  waiting  for  an  update  event  to  trigger 
its  display.  It  does  this  by  having  its  own  little  update  routine: 


procedure  ShowPleaseWait; 

var  r         :  Rect; 

origPort   :  GrafPortPtr; 
msgWindPtr:  GrafPortPtr; 

begin 

origPort    :=  GetPort; 
msgWindPtr  := 

GetNewModalDialog(@PlsWtTemp) • 
SetRect (r, 70, 19,  640,  200)  ; 
NewDItem  ( 

msgWindPtr, 1502, r, 15, 

@ 'Please  wait  while  we  set  things  up 

0,0, Pointer (0) ); 
BeginUpdata  (msgWindPtr) ; 
DrawDialog   (msgWindPtr) ; 
EndOpdato    (msgWindPtr) ; 
end; 


{begin  ShowPleaseWait...} 

(rectangle  to  display  dialog  in) 
(common  variable  with  HidePleaseWait) 
(common  variable  with  HidePleaseWait) 


(Save  the  current  Graf Port) 
(Open  the  dialog,  with  the  template, 
{...created  in  InitGlobals) 
{Define  rectangle  dimensions) 
{Create  an  item  for  the  dialog:) 
{...with  these  parameters...) 
{...displaying  this  string...} 
{...and  with  these  other  parameters) 
{Treat  this  like  an  update...} 
{...manually  draw  the  dialog...} 
{...and  end  the  update-handling} 
{End  of  ShowPleaseWait) 


procedure   HidePleaseWait; 


begin 

CloseDialog    (msgWindPtr)  ; 
(origPort)  ; 


SetPort 


end; 


{begin  HidePleaseWait...} 


{Remove  dialog  from  the  screen) 
{Restore  the  original  GrafPort} 
{End  of  HidePleaseWait} 
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Figure  4-11  shows  what  the  dialog  box  created  by 
ShowPleaseWait  looks  like.  It  is  a  message  dialog  box  because  it 
requires  no  response  from  the  user,  and  disappears  on  its  own 
when  no  longer  needed. 


Please  wait  while  we  set  things  up. 


Figure  4-11 

HodgePodge  message  dialog  box 


If  you  want  to  write  a  custom  alert 
sound  procedure,  see 
"Miscellaneous  Tool  Set"  and 
"Sound  Tool  Set"  In  the  Apple  IIGS 
Toolbox  Reference. 


Alerts 

With  alerts,  your  applications  have  a  standardized  way  to  report 
errors  or  give  warnings.  An  alert  box  is  similar  to  a  modal  dialog 
box,  but  appears  only  when  something  has  gone  wrong  or  must  be 
brought  to  the  user's  attention.  The  alert  box  is  usually  placed 
slightly  farther  below  the  menu  bar  than  a  dialog  box.  To  help  the 
user  who  isn't  sure  how  to  proceed  when  an  alert  box  appears,  the 
preferred  button  to  use  in  the  current  situation  is  doubly  outlined 
so  that  it  stands  out  from  the  other  buttons  in  the  alert  box.  The 
outlined  button  is  the  alert  box's  default  button;  if  the  user  presses 
the  Return  key,  the  effect  is  the  same  as  clicking  this  button. 

There  are  three  standard  kinds  of  alerts — Stop,  Note,  and 
Caution — each  indicated  by  a  particular  icon  in  the  upper-left 
corner  of  the  alert  box.  Figure  4-12  illustrates  a  Stop  alert.  You  can 
put  anything  you  like  in  the  upper-left  corner  of  an  alert,  including 
blank  space. 

The  alert  mechanism  also  provides  another  type  of  signal:  sound 
from  the  speaker.  The  application  can  base  its  response  on  the 
number  of  consecutive  times  an  alert  occurs;  the  first  time,  it 
might  simply  beep,  and  thereafter  it  may  present  an  alert  box. 
The  sound  isn't  limited  to  a  single  beep  but  may  be  any  sequence 
of  tones,  and  may  occur  either  alone  or  along  with  an  alert  box. 
As  an  error  is  repeated,  there  can  also  be  a  change  in  which 
button  is  the  default  button  (perhaps  from  OK  to  Cancel).  You 
can  specify  different  responses  for  up  to  four  occurrences  (.stages) 
of  the  same  alert. 
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Hodgepodge's  main  error  handler,  CheckDiskError  is  an 
example  of  a  routine  that  puts  up  a  Stop  alert  (Figure  4-12)  The 
exact  message  displayed  depends  on  the  particular  error  that 
occurred   CheckDiskError  is  listed  and  described  under  "Error 
Handling    in  Appendix  D.  Some  of  its  features  are  described 
under  "Item  Lists,"  later  in  this  section 


Figure  4-12 

HodgePodge  Stop  alert 


Dialog  and  alert  windows 

A  dialog  box  appears  in  a  dialog  window.  When  you  call  a  Dialog 

taS3r  r°Utm\t0  CreatG  a  dial°8'  y°U  SUP^  the  same  ki"d  of 

™T  ^  Wh6n  y°U  Create  a  Window  with  a  Window  Manage: 
wTnHn    L°U  Can  man'Pulate  a  mod^ess  dialog  window  with 
Window  Manager  or  QuickDraw  routines,  just  like  any  other 
window-showing  it,  hiding  it,  moving  it,  or  changing  its  size  and 

&  bo  ermt  .If  r want  ciipping  to  °ccur-  v£  -  si 

dialog  box  GrafPort's  clipping  region  with  QuickDraw  calls. 

teltv°n*T*TS  inT  aIen  Wind°W-  Y°u  don>t  have  *e  same 
The  D  Tol  m  8  lnd  maniPulatin8  «  alert  window,  however. 

ihZ  J?  !r        T'    u°°SeS  thC  Wind°W  definition  P^edure,  so 
that  a u  alert  windows  have  a  standard  appearance  and  behavior 
The  S12e  and  location  of  the  box  are  supplied  as  part  of  the 
definition.  You  don't  specify  the  alert  window's  pfane;  it   Iways 
comes  up  in  front  of  all  other  windows.  Because  an  aiert  box 
requires  the  user  to  respond  before  doing  anything  else  and  the 
response  makes  the  box  go  away,  the  application  doe  n't 
manipulate  the  alert  window. 
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Item  ID's  are  discussed  in  this 
section,  under  "Item  Lists." 


Dialog  records 

To  create  a  dialog,  you  pass  information  to  the  Dialog  Manager, 
with  which  it  creates  a  dialog  record.  The  dialog  record  contains 
the  window  record  for  the  dialog  window,  a  handle  to  the  dialog's 
item  list,  and  some  additional  fields.  The  Dialog  Manager  creates 
the  dialog  window  by  calling  the  Window  Manager. 

The  Dialog  Manager  passes  to  your  application  a  pointer  to  the 
dialog  port,  which  you  use  thereafter  to  refer  to  the  dialog  in 
Dialog  Manager  routines  or  even  in  Window  Manager  or 
QuickDraw  II  routines.  The  dialog  pointer  is  equivalent  to  the 
window  pointer  for  the  dialog  box.  It  is  not  a  pointer  to  the  dialog 
record  or  even  to  the  window  record.  It  is  a  pointer  to  the 
GrafPort  record  only. 

You  can  do  all  the  necessary  operations  on  a  dialog  without 
accessing  the  fields  of  the  dialog  record  directly.  To  get  or  change 
information  about  an  item  in  a  dialog,  you  pass  the  dialog  pointer 
and  the  item  ID  to  a  Dialog  Manager  routine.  You'll  rarely  access 
information  directly  through  the  handle  to  the  item. 


If  an  item  is  enabled,  the  Dialog 
Manager  notifies  the  application 
whenever  the  user  selects  the 
item. 


Items 

A  dialog  box  or  alert  is  a  window  with  items.  To  create  a  dialog 
box  or  an  alert,  the  Dialog  Manager  needs  to  know  what  items  the 
window  contains.  It  also  needs  to  know  the  following  information 
for  each  item: 

a  The  item  type.  This  includes  not  only  whether  the  item  is  a 
standard  control,  editable  text,  or  other  type,  but  also  whether 
it  is  enabled. 

d  A  display  rectangle,  which  determines  the  location  of  the  item 
within  the  dialog  or  alert  box. 

□  An  item  ID  number  uniquely  identifying  the  item  in  the  dialog. 
All  subsequent  Dialog  Manager  calls  referring  to  that  item  will 
need  its  ID  number. 

□  Other  information  specific  to  certain  types  of  items,  such  as  the 
item's  title,  its  initial  value,  its  colors,  its  orientation,  and 
whether  it  is  visible  or  invisible. 
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Figure  4-13 
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The  view  rectangle  and  other 
aspects  of  UneEdit  are  described 
under  "UneEdit  Tool  Set"  In  the 
Apple  IIGS  Toolbox  Reference. 


Display  rectangle 

Each  item  in  the  item  list  is  displayed  within  its  display  rectangle: 

a  For  standard  controls,  scroll  bars  and  user  controls,  the  display 
rectangle  becomes  the  control's  enclosing  rectangle. 

□  For  an  editable  text  item,  it  becomes  LineEdit's  view  rectangle. 
The  text  is  clipped  (not  drawn)  wherever  it  extends  beyond  the 
rectangle.  In  addition,  the  Dialog  Manager  uses  QuickDraw  II  to 
draw  a  bordering  rectangle  outside  the  display  rectangle. 

□  Static  text  items  are  displayed  in  generally  the  same  way  as 
editable  text  items,  except  that  a  rectangle  isn't  drawn  outside 
the  display  rectangle.  Also,  there  are  three  different  formats  for 
static  text. 

□  Icons  are  aligned  with  the  display  rectangle's  origin. 

♦  Note:  Clicking  anywhere  within  the  display  rectangle  is 

considered  a  click  in  that  item.  If  display  rectangles  overlap,  a 
click  in  the  overlapping  area  is  considered  a  click  in  whichever 
item  comes  first  in  the  item  list. 


Item  ID 

Each  item  in  an  item  list  is  identified  by  an  item  ID,  a  unique 
number  within  the  list.  By  convention,  the  OK  button  in  an  alert's 
item  list  should  have  an  ID  of  1  and  the  Cancel  button  should 
have  an  ID  of  2.  The  Dialog  Manager  provides  predefined 
constants  equal  to  the  item  ID  for  OK  and  Cancel,  as  follows: 

ok  =1 

cancel  =     2 

In  a  modal  dialog's  item  list,  the  item  whose  ID  is  1  is  assumed  to 
be  the  dialog's  default  button  (unless  specified  otherwise);  if  the 
user  presses  the  Return  key,  the  Dialog  Manager  normally  returns 
the  ID  of  the  default  button,  just  as  when  that  item  is  actually 
clicked. 

To  conform  with  the  Apple  Human  Interface  Guidelines,  the 
Dialog  Manager  automatically  outlines  the  default  button  in  bold, 
unless  there  is  no  default  button  (that  is,  no  button  item  with  ID 
1). 

♦  Note:  If  you  don't  want  a  default  button,  do  not  create  any  item 
with  an  ID  of  1. 
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Example 


MakeATemplate  is  In  the  source 
file  DIALOG.PAS. 


MakeATemplate  is  a  routine  called  by  CheckDiskError 
(described  earlier  and  listed  in  Appendix  D)  in  order  to  fill  in  the 
dialog  record  and  the  item  list  for  the  HodgePodge  stop  alert 
shown  in  Figure  4-12.  MakeATemplate  describes  the  basic  alert  i 
box,  including  what  is  to  happen  at  each  stage,  and  defines  two 
items:  an  OK  button  for  the  user  to  click,  and  a  static  text  item  that 
contains  the  error  message. 


procedure  MakeATemplate    (   TheTemplate : 

AlertTempPtr; 
TheStr:    StringPtr) ; 

var  currentlteml :    ItemTemplate; 

currentltem2 :    ItemTemplate; 

begin 

with   TheTemplate"  do 
begin 
SetRact  (atBoundsRect, 120,30,520,  80)  ; 


atAlertID 

=   1500; 

at St age 1 

-  $80; 

atStage2 

=  $80; 

atStage3 

-  $80; 

atStage4 

=  $80; 

atlteml 

=  @ currentlteml; 

atltem2 

=  @currentltem2; 

atltem3 

-  NIL; 

end; 

with   currentlteml  do 
begin 
itemID     :=  1; 
SetRact  (itemRect, 320, 25, 0, 0) ; 


itemType 

=   10; 

itemDescr 

=  @'OK'; 

itemValue 

=  0; 

itemFlag 

=  0; 

itemColor 

-  NIL; 

end; 

with   currentltem2  do 
begin 
itemID    :=  2; 
SetRact  (itemRect,  72, 11,  639, 199)  , 


itemType 
itemDescr 
itemValue 
itemFlag 
itemColor 
end; 
end; 


=  15  +  $8000; 

=  Pointer  (TheStr) ; 

=  0; 

=  0; 

=  NIL; 


{begin  MakeATemplate...} 
{toolbox-defined  structure} 

{First  define  alert  box:} 
{bounding  rectangle  for  alert} 


{at  each  stage,  make  alert...} 
{...visible  but  silent} 

{ptr  to  first  item's  template} 
{ptr  to  2nd  item's  template} 
{terminates  item  list} 
{end  of  defining  box  template} 

{Now  define  item  1:J 

{item  #1  =  default  item} 
{display  rectangle} 
{ it ' s  a  buttton  item} 
{text  in  button} 
{initial  value  =0} 
{=default  style} 
{no  color} 
{end  of  item  1} 

{Now  define  item  2:} 


{display  rectangle} 

{disabled  static  text} 

{the  string  passed  to  this  routine} 

{no  initial  value} 

{default  style} 

{no  color} 

{end  of  item  2} 

{End  of  MakeATemplate} 
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Using  dialogs 

In  most  cases,  you  probably  won't  have  to  make  any  changes  to 
the  dialogs  from  the  way  they're  defined  at  their  creation. 
However,  there  are  calls  to  modify  items,  move  controls,  or 
change  text.  If  you  want  the  font  in  your  dialog  and  alert  windows 
to  be  something  other  than  the  system  font,  call  SetDAFont  to 
change  the  font. 

To  handle  events  in  a  modal  dialog,  call  the  routine  ModalDialog 
after  putting  up  the  dialog  box.  If  your  application  includes  any 
modeless  dialog  boxes,  they're  a  bit  more  complex  to  handle; 
part  of  your  event-handling  will  include  determining  whether 
events  need  to  be  handled  as  part  of  the  dialog  box.  You  can 
support  the  use  of  the  standard  cut,  copy,  paste,  and  delete  editing 
commands  in  a  modeless  dialog  box. 

You  can  substitute  text  in  static  text  items  with  text  that  you  specify 
in  the  ParamText  routine.  This  means,  for  example,  that  a 
document  name  supplied  by  the  user  can  appear  in  an  error 
message. 


The  desk  scrap  is  described 
under  "Supporting  Other  Desktop 
Features"  in  Chapter  5. 


Editing  text  with  LineEdit 

To  provide  simple  text-editing  capabilities  needed  for  dialog 
boxes  and  other  general  purposes,  the  Apple  IIGS  Toolbox 
includes  the  LineEdit  Tool  Set.  The  routines  in  LineEdit  provide 
basic  text-editing  capabilities  that  follow  the  Apple  Human 
Interface  Guidelines.  These  capabilities  include 

□  inserting  new  text 

□  deleting  characters  that  are  backspaced  over 

a  translating  mouse  activity  or  arrow  keys  into  text  selection 

□  deleting  selected  text  and  possibly  inserting  it  elsewhere 

□  copying  selected  text  without  deleting  it 

LineEdit  uses  inverse  highlighting  to  show  the  current  text 
selection,  or  a  blinking  vertical  bar  to  show  the  insertion  point. 
LineEdit  places  cut  or  copied  text  into  the  LineEdit 
scrap — different  from  the  desk  scrap. 
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LineEdit  is  not  a  complete  text  editor.  It  does  not  support 
a  more  than  256  characters  per  line  (except  when  using 
LETextBox  or  LETextBox2)  g 

□  fully  justified  text;  that  is,  text  aligned  with  both  the  left  and 
nght  margins  (except  when  using  LETextBox2) 

□  automatic  word  wrap  (except  when  using  LETextBox2) 

□  scrolling 

□  fonts  that  kern  characters 
n  tabs 

DIALOG.PAS.  *>  OoAbout  Itfm  „  the  subrouUne  „„,,  ^ 

dial™  ,"ie  Apple  menu-  Th^  subroutine  shows  how  to  create  a 
invoke  it  „ith  L  ca,l  JS;'  SS  fan  *"  „'  *" 
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procedure   DoAboutltem; 

var    aboutDlog  :  GrafPortPtr; 

r         :  Rect ; 

itemHit    :  Integer; 

applelconP:  Ptr; 

applelconH:  Handle; 

begin 

SetRect  (r, 146, 20, 495, 192) ; 
aboutDlog  :=  NewModalDialog (r, TRUE, 0) 

SetRect  (r, 270, 153, 0, 0) ; 
NawDItem (aboutDlog, 1, r, Buttonltem, 
@ 'OK',  0,0,  NIL); 

SetRect  (r,  20, 135,  0,  0) ; 

applelconP  :=  SApplelcon; 

applelconH  :=  SApplelconP; 

NewDItem (aboutDlog, 3,  r, 

iconltem+itemDisable, 
ApplelconH, 0,0, NIL); 


SetPort  (aboutDlog) 
SetForeColor  ( 0 ) ; 
SetBackColor  (15); 


(begin  DoAboutltem...} 

{pointer  to  this  dialog} 

{item  selected  by  user} 

{pointer  and  handle  to  the  Apple...} 

{...icon  created  in  InitGlobals} 

{=  rectangle  the  dialog  appears  in} 
{Open  the  dialog:  in  rectangle  r, 
visible,  no  reference  value} 
{Define  a  display  rectangle  and..} 
{...make  a  dialog  item  for  it:...} 
{...the  OK  button} 

{Define  another  display  rectangle...} 

{...get  a  handle  to  the  Apple  icon...} 

{make  it  a  disabled  icon  item} 

{For  the  rest  of  the  text,  simply 
write  it  directly  in  the  port, 
rather  than  creating  dialog  items} 

{make  sure  this  is  the  active  port} 
{foreground  color  =  black} 
{background  color  =  white} 


MoveTo  (40,17); 
SatTaxtFaca  (8)  ; 
Drawstring 

( '  HodgePodge ' ) ; 

SetTextFace  (0) ; 
MoveTo  (40,27); 
DrawString 

( '       A  potpourri  of  routines  that ' ) ; 
MoveTo  (40,37); 
DrawString 

('       demonstrate  many  features  of); 
MoveTo  (40,47); 
DrawString 

('  the  Apple  IIGS  Tools.'); 

MoveTo  (40,67); 
DrawString 

('       By  the  Apple  IIGS  Development  Team' )  ; 
MoveTo  (36,77); 
DrawString 

('Translated  to  TML  Pascal  by  TML  Systems'); 


{move  the  pen  to  starting  position...} 
{  (change  to  outline  text) } 

{Draw  the  first  line...} 

{ (go  back  to  plain  text) } 

{Move  to  next  line  and  continue...} 
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MovoTo    (4  0,87); 
Drawstring 

Moveio    (40,lCi°7PffghtAPPle  ^^    Inc-'" 
Drawstring 

('  1986-87     All    ,-i^v,*- 

MoveTo    (40,127);  rights   reserved- ); 

Drawstring 

V4.0-,      23-Sep-87'); 
itemHit    :=  ModalDialog (NIL)  ; 
CloseDialog (aboutDlog) ; 


end: 


{call  ModalDialog;  it  returns  when 
any  enabled  item  is  selected} 
{Close  the  Dialog  when  OK  clicked) 

{End  of  DoAboutltem} 


iXi^  this  roufae 

different  text  from  the  Pascafexamp"e)  SI°nS  ^  ^ 


J  Potpourri  of  routines  that 
demonstrate  many  features  of 
the  Apple  IIGS  Tools. 

Bathe  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems 

Copyright  Apple  Computer  Inc 


1986-87,  All  rights  reserved 
v4.0    23-Sep-87 


Figure  4-14 

The  "About  HodgePodge..."  dialog  box 
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This  chapter  concludes  our  brief  discussion  of  the  Apple  IIGS 
Toolbox.  The  tool  sets  described  here  can  help  you  accomplish 
these  tasks: 

□  creating  menus 

□  supporting  other  desktop  features  such  as  desk  accessories  and 
cut-and-paste 

□  accessing  external  devices  and  files 
D  generating  and  playing  sounds 

a  performing  mathematical  computations 

□  controlling  parts  of  the  Apple  IIGS  operating  environment 


Making  and  modifying  menus 

Pull-down  menus  are  an  important  part  of  the  desktop 
environment.  Menus  allow  users  to  examine  all  choices  available 
to  them  at  any  time  without  being  forced  to  choose  one  of  them, 
and  without  having  to  remember  command  words  or  special  keys, 

The  Menu  Manager  is  the  Apple  IIGS  tool  set  that  supports  menus 
of  the  style  recommended  by  the  Apple  Human  Interface 
Guidelines.  The  user  displays  a  menu  by  positioning  the  cursor  in 
the  menu  bar  and  pressing  the  mouse  button  over  a  menu  title 
The  Menu  Manager  highlights  the  selected  title  (by  redrawing  it  ir 
inverted  colors)  and  "pulls  down"  the  menu  below  it.  As  long  as 
the  mouse  button  is  held  down,  the  menu  is  displayed.  Dragging 
through  the  menu  causes  each  of  its  menu  items  (commands)  to 
be  highlighted  in  turn.  If  the  mouse  button  is  released  over  an 
item,  that  item  is  considered  chosen.  The  item  blinks  briefly  to 
confirm  the  choice,  and  the  menu  disappears. 

When  the  user  chooses  an  item,  the  Menu  Manager  tells  the 
application  which  item  was  chosen,  and  the  application  performs 
the  corresponding  action.  When  the  application  completes  the 
action,  it  removes  the  highlighting  from  the  menu  title,  indicating 
to  the  user  that  the  operation  is  complete. 

If  the  user  moves  the  cursor  out  of  the  menu  with  the  mouse 
button  held  down,  the  menu  remains  visible,  though  no  menu 
items  are  highlighted.  If  the  mouse  button  is  released  outside  the 
menu,  no  choice  is  made;  the  menu  just  disappears  and  the 
application  takes  no  action.  The  user  can  always  look  at  a  menu 
without  causing  any  changes  in  the  document  or  on  the  screen. 
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All  applications  should  support 
desk  accessories.  See 
"Supporting  Other  Desktop 
Features."  later  in  this  chapter. 


Menu  bars 

A  menu  bar  is  an  outlined  rectangle  that  holds  the  titles  of  all  the 
menus  associated  with  the  bar.  A  menu  in  the  bar  may  be  enabled 
or  temporarily  disabled.  A  disabled  menu  can  still  be  pulled 
down,  but  its  title  and  all  the  items  in  it  are  dimmed  and  not 
selectable. 

The  principal  menu  bar  is  the  system  menu  bar;  see  Figure  5-1. 
There  can  only  be  one  system  menu  bar  on  the  screen  at  one 
time.  The  system  menu  bar  always  appears  at  the  top  of  the  Apple 
IIGS  screen;  nothing  but  the  cursor  ever  appears  in  front  of  it.  In 
applications  that  support  desk  accessories,  the  first  (leftmost) 
menu  should  be  the  desk  accessory  menu  (also  called  Apple 
menu,  the  menu  whose  title  is  a  colored  apple  symbol).  The  desk 
accessory  menu  contains  the  names  of  all  available  desk 
accessories,  and  usually  the  name  of  a  dialog  box  that  gives  brief 
information  about  the  application  itself.  When  the  user  chooses  a 
desk  accessory  from  the  menu,  the  title  of  the  menu  belonging  to 
the  desk  accessory  may  appear  in  the  menu  bar  for  as  long  as  the 
accessory  is  active,  or  the  entire  menu  bar  may  be  replaced  by 
menus  belonging  to  the  desk  accessory. 


Titles  of  enabled  menus     Titles  of  disabled  menus 


Menu  bar{ 


*  File  Edit  View  Special  Color 


Figure  5-1 

The  system  menu  bar 


Window  menu  bars  are 
described  under  "Menu 
Manager"  in  the  Apple  IIGS 
Toolbox  Reference. 


In  addition  to  the  system  menu  bar,  your  application  can  have 
various  window  menu  bars.  These  can  appear  anywhere  on  the 
screen  and  in  windows.  Window  menu  bars  are  provided  to  give 
you  more  menu  space,  particularly  because  of  the  limited 
resolution  in  320  mode.  Window  menu  bars  should  be  used 
moderately,  if  at  all. 
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A  shadowed  rectangle  is  one  that 
appears  to  have  a  thin  shadow 
just  below  and  to  the  right  of  it. 
making  it  appear  to  stand  out 
slightly  from  the  desktop. 


Menu  appearance 

A  standard  menu  consists  of  a  number  of  menu  items  listed 
vertically  inside  a  shadowed  rectangle.  Items  on  a  menu  may  be 
the  text  of  a  command,  a  solid  color,  or  just  a  line  dividing 
groups  of  choices.  Menus  always  appear  in  front  of  everything 
except  the  cursor.  Figure  5-2  shows  a  menu  with  six  items, 
including  two  dividing  lines. 


Keyboard  equivalent- 
Items 


Dividing  line- 
Mark 


Disabled  item- 


Figure  5-2 

A  standard  menu 


Figure  5-2  shows  some  of  the  typical  variations  in  an  item's 
appearance: 

□  A  mark  may  appear  on  the  left  side  of  the  item,  to  denote  the] 
status  of  the  item  or  of  the  mode  it  controls. 

□  An  Apple  logo  followed  by  a  capital  letter  may  appear  to  the  I 
right  of  the  item,  to  show  that  the  item  may  be  invoked  from 
the  keyboard  (that  is,  it  has  a  keyboard  equivalent).  If  the  user 
presses  the  letter  key  while  holding  down  the  Apple  key,  the 
menu  item  is  invoked  just  as  if  it  had  been  chosen  from  the 
menu. 

□  Each  item's  text  may  have  its  own  text  style. 

□  An  item  can  be  dimmed  to  indicate  that  it  is  disabled  and 
can't  be  chosen. 

□  A  dividing  line  is  a  separate  menu  item.  Dividing  lines  should 
always  be  disabled. 
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See  "Menu  Manager"  In  the 
Apple  IIGS  Toolbox  Referenced 
Information  on  how  to  create 
custom  menus. 


If  a  standard  menu  doesn't  suit  your  needs — for  example,  if  you 
want  more  graphics,  or  perhaps  a  nonlinear  text  arrangement — 
you  can  write  a  custom  menu  definition  procedure.  The  Menu 
Manager  will  call  that  procedure  when  it  draws  the  menu.  The 
custom  menu  can  be  visibly  very  different,  and  yet  respond  to 
your  application's  Menu  Manager  calls  just  like  a  standard  menu. 
The  items  in  the  menu  can  have  any  appearance. 


Keyboard  equivalents 

Your  program  can  set  up  a  keyboard  equivalent  for  any  of  its 
menu  commands  in  order  to  allow  the  user  to  invoke  the 
command  from  the  keyboard.  The  character  you  specify  for  a 
keyboard  equivalent  should  be  a  letter  that  the  user  can  type  in 
either  uppercase  or  lowercase.  For  example,  typing  either  "G"  or 
"g"  while  holding  down  the  Apple  key  invokes  the  command 
whose  equivalent  is  "(3  G." 

♦  Note.-  For  consistency  among  applications,  you  should  specify 
the  letter  in  uppercase  in  the  menu. 


Constructing  menus 

It's  simple  to  construct  your  application's  menus.  All  you  need  to 
do  is  define  the  text  of  the  menu  titles  and  items,  and  assign  ID 
numbers  to  each  menu  title  and  item. 

♦  Note:  The  menu  bar  does  not  allow  for  a  large  number  of 
menus  or  menus  with  lengthy  titles.  If  you're  having  trouble 
fitting  your  menus  into  the  menu  bar,  you  should  review  their 
organization  and  titles.  Furthermore,  if  your  program  is  likely  to 
be  translated  into  other  languages,  remember  that  translated 
menu  titles  may  take  up  more  space. 


Menu  lines  and  item  lines 

You  create  menus  by  constructing  a  list  of  menu  and  item  lines, 
and  passing  a  pointer  to  that  list  to  the  NewMenu  routine. 
NewMenu  parses  the  menu  and  item  lines,  allocates  enough 
memory  for  necessary  records,  and  initializes  those  records.  The 
menu  and  item  lines  must  remain  in  memory  as  long  as  the  menu 
exists. 
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The  list  must  follow  a  specific  syntax;  here  is  an  example: 


For  a  complete  discussion  of 
menu-  and  item-line  syntax, 
including  a  description  of  all 
special  characters,  see  "Menu 
Manager"  in  the  Apple  IIGS 
Toolbox  Reference. 


>>Title  1\N1 
— Item  string  1\N256 
— Item  string  2\N257 
— Item  string  3\N258 

This  is  a  simple  list  of  one  menu  line  and  three  item  lines.  The 
first  character  on  the  first  line  is  the  title  character;  it  denotes  the 
start  of  a  menu.  The  first  character  on  any  line  other  than  a  title 
line  is  the  item  character;  it  denotes  an  item  in  the  menu.  The 
second  character  in  each  line  can  be  anything  (it  is  changed  by 
the  Menu  Manager) — here  it  just  repeats  the  first  character.  Each 
line  is  terminated  by  a  return  (decimal  13)  or  a  null  byte  (0). 
Finally,  a  termination  character,  different  from  the  menu  and  item 
character,  denotes  the  end  of  the  list. 

In  the  example  above,  ">"  is  the  title  character,  "-"  is  the  item 
character,  and  a  period  is  the  termination  character.  But  you  may 
use  any  characters,  as  long  as  the  title  and  item  characters  are 
different,  and  the  termination  character  is  different  from  the  item 
character.  (Thus,  the  title  and  termination  character  may  be  the 
same.) 

Before  the  terminating  character  of  each  line,  "N"  followed  by  a 
number  specifies  the  menu  and  menu  item  ID  number. 

For  an  example  of  menu  and  item  lines  using  multiple  special 
characters  and  different  title,  item,  and  terminating  characters,  see 
the  HodgePodge  source  code  listing  of  initGlobals,  under 
"Start  the  Program"  in  Chapter  2.  In  InitGlobals  the  title 
character  is  ">",  the  item  character  is  "=",  and  the  termination 
character  is  a  period.  The  second  character  in  each  line  repeats 
the  first.  You  can  see  from  the  listing  that,  depending  on  how  you 
want  your  menus  to  appear,  the  syntax  can  be  quite  complex. 

Using  just  the  "@"  symbol  in  a  title  provides  the  Apple  logo.  The 
@  must  follow  the  character  denoting  a  menu  title,  and  then  be 
followed  by  an  end-of-line  mark  (carriage  return).  Do  not  place  a 
space  before  or  after  the  @,  as  you  must  with  other  menu  titles. 
See  the  InitGlobals  example. 
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Menu  and  item  ID  numbers 

ID  numbers  are  assigned  in  the  menu/item  line  list.  The  ID 
numbers  must  be  allocated  as  shown  in  Table  5-1. 


Important 


A  Menu  ID  must  be  unique  for  each  menu;  that  Is,  no  two  menus  can 
have  the  same  ID.  Similarly,  no  two  items,  whether  In  the  same  or 
separate  menus,  can  have  the  same  Item  ID. 


Table  5-1 

Menu  ID  number  assignment 


Hexadecimal 

Decimal 

Meaning 

Menu  ID  numbers 

$0000 

0 

Internal  use,  generally  means 
front,  or  first  menu  in  bar. 

$0001-$FFFE 

1-65534 

Reserved  for  application  use. 

$FFFF 

65535 

Internal  use,  generally  means 
end,  or  last  menu  in  bar. 

Item  ID  numbers 

$0000 

0 

Internal  use,  generally  means 
front,  or  first  item  in  menu. 

$0001  -  $00F9 

1-249 

Reserved  for  desk  accessory 
items. 

$00FA 

250 

Undo  edit  item. 

$00FB 

251 

Cut  edit  item. 

$00FC 

252 

Copy  edit  item. 

$00FD 

253 

Paste  edit  item. 

$00FE 

254 

Clear  edit  item. 

$00FF 

255 

Close  command  item. 

$0100  -  $FFFE 

256-65534 

Reserved  for  application  use. 

$FFFF 

65535 

Internal  use,  generally  means 

end,  or  last  item  in  menu. 
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HodgePodge  uses  symbolic  constants  for  menu  ID  numbers  in  its 
menu-  and  item-line  definitions.  It  assigns  menu  ID's  to  those 
constants  in  the  file  GLOBALS  .pas,  as  follows: 


AppleMenuID 

=  300 

About Item 

=  301 

FileMenuID 

=  400 

Open  Item 

=  401 

Closeltem 

=  255 

SaveAsItem 

=  403, 

ChoosePItem 

=  405, 

PageSetltem 

=  406, 

Printltem 

=  407; 

Quitltem 

=  409; 

EditMenuID 

=  500; 

Undoltem 

=  250; 

Cutltem 

=  251; 

Copyltem 

=  252; 

Pasteltem 

=  253; 

Clearltem 

=  254; 

WindowsMenuID 

=  600; 

NoWindowsItem 

=  601; 

FirstWindltem 

=  2000; 

FontsMenuID 

=  700; 

Fontltem 

=  701; 

Monoltem 

=  7  02; 

{reserved  ID  number) 
{reserved  ID  number} 
{reserved  ID  number} 
{reserved  ID  number} 
{reserved  ID  number} 


{window  menu  ID's  are  allocated 
dynamically  starting  at  2000} 


How  HodgePodge  sets  up  the  menu  bar  when  the  program 
executes  is  demonstrated  in  Chapter  2. 


Accepting  user  input 

How  your  application  responds  to  menu  selections  made  by  the 
Taster  ^  "  "^  °f  not  lhe  ^li™ion  c^ 

eTch^m  JT**T 'I  ^  aPPlication  tyP^ally  calls  GetNextEvent 
each  time  through  the  event  loop.  If  the  user  selects  a  menu  item 

7:hP:im:z{oi:ouse-down  evem  occurs  and  the  ■«*«*» 

1.  It  calls  FindWindow,  which  (in  this  case)  returns  to  the 

taS^„t£Lfafom,atton  that  the  mouse  bu»°n  -  P-ed 
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changes  in  cursor  position 
betwen  the  time  a  mouse  button 
is  pressed  and  when  it  is  released. 
That  way  a  user's  selection  is  not 
finalized  until  the  mouse  button  is 
released. 


DoMenu  Is  listed  and  described 
under  "Handle  Specific  Events"  in 
Chapter  2. 


2.  It  then  calls  MenuSelect,  which  tracks  the  mouse,  opening 
menus  and  highlighting  selections  until  the  mouse  button  is 
released.  If  it  is  released  in  a  menu  selection,  MenuSelect 
returns  to  the  application  the  number  of  the  menu  and  the 
number  of  the  item  in  the  menu  that  was  selected.  It  also 
highlights  the  menu's  title. 

3.  The  application  then  branches  to  the  subroutine  that  handles 
the  menu  item  selected. 

4.  When  the  task  is  completed,  the  application  unhighlights  the 
menu  title  and  continues  in  the  main  event  loop. 

♦  Keyboard  equivalent:  If  the  menu  item  was  selected  with  its 
equivalent  keystroke  combination  rather  than  with  the  mouse,  a 
key-down  event  occurs.  The  application  must  look  at  the 
modifiers  field  of  the  event  record  to  know  that  the  Apple  key 
was  pressed  at  the  same  time,  meaning  a  menu  selection  has 
been  made.  The  application  then  highlights  the  menu  title  and 
proceeds  from  step  3  (above). 

On  the  other  hand,  if  your  application  calls  TaskMaster  instead  of 
GetNextEvent  each  time  through  the  event  loop,  most  of  the 
above  procedure  is  handled  automatically.  For  both  mouse-down 
and  key-down  events,  TaskMaster  takes  care  of  finding  out  whether 
they  represent  menu-selection  actions.  If  the  user  selects  a  menu 
item  with  the  mouse  or  with  a  keyboard-equivalent,  TaskMaster 
highlights  the  menu  and  returns  a  task  code  of  wlnMenuBar 
(meaning  a  menu  selection  was  made).  Your  application  can 
examine  the  taskData  field  of  the  extended  task  event  record  to 
see  which  item  in  which  menu  was  selected.  Then  it  can  branch 
directly  to  the  appropriate  subroutine. 

♦  HodgePodge:  HodgePodge  uses  TaskMaster.  After  receiving  a 
wlnMenuBar  task  code  from  TaskMaster,  HodgePodge  jumps 
to  its  menu-event  dispatcher,  DoMenu.  DoMenu  gets  the 
individual  menu  item's  ID  number  from  the  Event  . taskDatc 
field  of  the  extended  event  record,  and  jumps  to  the  proper 
subroutine. 
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AddToMenu  is  in  the  source  file 
MENU. PAS. 


Modifying  menus  during  execution 

If  your  menu  bar,  or  items  in  a  menu,  are  going  to  change  while 
on  the  screen,  you  can  use  Menu  Manager  calls  to  rearrange  the 
menus  and  items.  In  the  routine  AddToMenu  (called  from  the 
routine  DoMenuItem),  HodgePodge  adds  a  new  item  to  the 
Windows  menu  when  a  new  window  is  opened  on  the  desktop. 
AddToMenu  does  this  principally  by  calling  InsertMItem  and 
DeleteMItem.    AddToMenu  also  adjusts  the  window  list—a  list  of 
pointers  to  all  open  windows. 


procedure   AddToMenu; 

rar    theWindow    :  GrafPortPtr; 
myDataHandle :  WindDataH; 

begin 

theWindow    :=  FrontWindow; 
windowList [wlndex]     :=  theWindow; 
myDataHandle    :=  WindDataH ( 

GetWRef Con  (theWindow) ) 

InsertMItem (@myDataHandleA * . menuStr [ 1 ]  , 
$FFFF,WindowsMenuID) ; 

if  wlndex  =   0   then 
begin 

DeleteMItem (NoWindowsItem) ; 
SetMenuFlag ($FF7F, WindowsMenuID)  ; 
DrawMenuBar; 
end; 


{begin  AddToMenu...} 


{window-data-record  handle} 


{Get  a  pointer  to  the  front  window...} 
{add  the  pointer  to  the  window  list} 
{...then  get  a  handle  to  its...} 
{...window-data  record,  to  get  name} 

{Insert  window's  name  at  the  end..} 
{...of  the  Windows  menu} 

{If  this  is  the  first  open  window...} 

{...remove  "No  Windows  Allocated"  item} 
{...enable  the  Windows  menu...} 
{..and  draw  it} 


CalcMenuSize (0,0, WindowsMenuID) 
Inc (wlndex)  ; 


end; 


{Recalculate  the  size  of  the  menu} 
{Increment  the  number  of  open  windows} 
{End  of  AddToMenu} 


The  above  example  shows  how  HodgePodge  adds  items  to  a 
menu.  On  the  other  hand,  when  windows  are  removed  from  the 
desktop,  HodgePodge  deletes  the  corresponding  menu  item  with 
code  in  the  routine  AdjWind.  AdjWind  is  called  from 
DoCloseltem   when  the  user  selects  Close  from  the  File  menu  or 
when  the  user  clicks  the  close  box  of  the  frontmost  window. 
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AdjWind  is  in  the  source  file 
WINDOW. PAS. 


AdjWind  makes  the  menu-related  calls  InsertMItem,  DeleteMItem 
and  CalcMenuSize.  It  also  adjusts  the  window  list  to  reflect  the  fact 
that  a  window  has  been  removed. 


procedure  AdjWind    (TheWindow:    GrafPortPtr) ; 


{begin  AdjWind..} 


1 
theOne 


Integer; 
Integer; 


begin 

i  :=  FirstWind; 

while  windowList [i]  <>  TheWindow  do 

Inc  (i); 
theOne :=i; 

if  wlndex  =   1   then 
begin 
InsertMItem (@noWindStr[l]  , 

FirstWindltem+theOne , 
WindowsMenuID)  ; 
SetMenuFlag($0080,WindowsMenuID)  ; 
DrawMenuBar; 
wXoffset    :=  20; 
wYoffset    :=   12; 
end; 

DeleteMItem (f irstWindltem+theOne) ; 
CalcMenuSize (0, 0, WindowsMenuID) ; 

Inc  (i)  ; 

while  i  <  lastWind  do 
begin 

windowList [i-1]  :=windowList [i] ; 
Inc  (i)  ; 
end; 


{start  with  menu  ID  of  1st  window} 
{...and  run  through  the  window  list} 

{...to  get  this  window's  position.} 

{If  we're  closing  the  LAST  window...} 

{...reinsert  "No  Windows  Allocated"...} 

{..after  this  item...} 

{...in  the  Windows  menu.} 

{...disable  the  Windows  menu...} 

{...redraw  the  menu  bar...} 

{...and  reinitialize  the  position...} 

{...of  the  next -opened  window} 

{end  of  IF  its  the  last  window} 

{Delete  item  on  the  Windows  menu...} 
{...and  recalculate  size  of  the  menu} 

{Now  go  to  the  next  window  on  list} 
{...and  for  each  window  in  turn...} 
{move  it  down  one  position...} 
{...in  the  window  list} 


for   i  :=  theOne  to  lastWind  do 
SetMItemID  (f irstWindltem+i-l, 

firstWindltem+i)  ; 


end; 


{now  renumber  items  in  Windows  menu:} 
{its  new  ID  number} 
{its  old  ID  number} 

{End  of  AdjWind} 


Note:  AdjWind  performs  some  rather  complex  manipulations 
of  pointer  lists  and  menu  IDs.  Your  program  can  easily  remove 
menu  items  without  going  through  such  acrobatics  if  menu  item 
IDs  are  not  going  to  change  and  if  menu  changes  do  not 
require  adjustment  of  other  lists  in  memory. 
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Supporting  other  desktop  features 

Two  other  important  desktop-programming  features  have  tool  sets 
that  support  them.  The  Desk  Manager  controls  desk  accessories 
(called  from  the  Apple  menu)  and  the  Scrap  Manager  handles 
cutting,  copying,  and  pasting  from  the  Edit  menu. 


Just  what  kind  of  control  an  NDA 
exercises  is  described  under 
"Desk  Manager"  in  the  Apple  IIGS 
Toolbox  Reference. 


Desk  accessories 

Any  application  you  write  should  support  desk  accessories.  Desk 
accessories  are  short  programs  such  as  clock  displays,  note  pads, 
and  calculators  that  a  user  might  want  to  access  without  having  to 
leave  your  program.  Desk  accessory  support  is  a  convenience  for 
the  user,  it  enhances  the  multitasking  feel  of  the  desktop,  and  it  is 
consistent  with  the  aims  of  the  Human  Interface  Guidelines. 
Furthermore,  it's  easy  to  include  in  your  programs. 

The  Desk  Manager  is  the  tool  set  that  enables  your  application  to 
support  desk  accessories.  There  are  two  types  of  desk  accessories 
in  the  Apple  IIGS  environment:  classic  desk  accessories  and  new 
desk  accessories. 

■  Classic  desk  accessories  (CDA's)  are  desk  accessories  designed 
to  function  in  a  non-desktop,  non-event-driven  environment. 
Unlike  new  desk  accessories,  a  CDA  gets  full  control  of  the 
computer  during  what  is  basically  an  interrupt  state  (generated 
by  a  keypress).  The  desk  accessory  is  responsible  for  saving  and 
restoring  any  of  the  application's  memory  that  it  uses,  as  well 
as  handling  all  I/O.  The  Control  Panel  is  a  classic  desk 
accessory. 

■  New  desk  accessories  (NDA's)  are  desk  accessories  designed 
to  execute  in  a  desktop,  event-driven  environment.  NDA's  run 
in  a  window  and  get  control  when  that  window  is  the  frontmost 
window. 

♦  Macintosh  Programmers.-  New  desk  accessories  are  the  style  of 
desk  accessories  available  on  the  Macintosh. 
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See  "Controlling  the  Apple  IBS 
Operating  Environment"  in  this 
chapter,  and  "The  Scheduler"  in 
the  Apple  IIGS  Toolbox  Reference 
for  more  information  on  the  Busy 
flag. 

If  you  want  to  write  a  classic  desk 
accessory  (CDA).  see  Chapter  8 
of  this  book. 


Supporting  classic  desk  accessories 

A  user  activates  a  classic  desk  accessory  from  the  CDA  menu.  The 
CDA  menu  is  displayed  by  pressing  Apple-Control-Escape  at  any 
time  during  program  execution.  Two  CDA's  are  built  into  the 
system: 

□  Control  Panel 

□  Alternate  Display  Mode 

Any  others  (up  to  eleven)  are  loaded  from  disk.  From  the  CDA 
menu,  a  user  can  select  any  of  the  CDA's  currently  in  the  system. 
The  desk  accessory  selected  is  activated  and  retains  control  until 
it  shuts  down.  When  it  shuts  down,  the  Desk  Manager  redisplays 
the  CDA  menu.  Only  when  the  user  selects  Quit  from  the  CDA 
menu  does  the  original  application  resume  operation. 

When  can  the  CDA  menu  be  displayed?  The  Desk  Manager  gets 
control  in  two  ways.  If  the  Event  Manager  is  active,  the  Desk 
Manager  is  called  in  conjunction  with  GetNextEvent.  If  the  Event 
Manager  is  not  active,  the  Desk  Manager  gets  control  whenever 
the  user  presses  Apple-Control-Escape,  which  generates  an 
interrupt.  Before  the  Desk  Manager  displays  the  CDA  menu,  it 
checks  the  system  Busy  flag.  If  something  in  the  system  is  busy, 
the  Desk  Manager  waits  until  the  Busy  flag  is  cleared,  then  "wakes 
up"  and  displays  the  CDA  menu.  This  guarantees  that  CDA's  have 
all  system  resources  available  to  them  when  they  are  called. 

The  only  thing  your  application  needs  to  do  to  support  classic 
desk  accessories  is  make  sure  that  interrupts  are  not  disabled  for 
long  periods. 


Supporting  new  desk  accessories 

New  desk  accessories  are  loaded  automatically  by  the  operating 
system  at  boot  time.  An  application  that  wants  to  make  NDA's 
available  to  the  user  does  not  have  to  do  a  lot  of  work,  particularly 
if  the  application  is  using  the  Window  Manager  routine  TaskMaster. 
By  convention,  however,  desk  accessories  can  assume  that  the 
following  tool  sets  are  already  available  for  them  to  use,  so  the 
application  must  make  sure  that  they  are  loaded  and  started  up: 

□  Tool  Locator 

□  Memory  Manager 

□  Miscellaneous  Tool  Set 
D  QuickDraw  II 

□  Event  Manager 
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D  Window  Manager 

□  Control  Manager 
D  Menu  Manager 

□  LineEdit  Tool  Set 

□  Dialog  Manager 

□  Scrap  Manager 

With  TaskMasfer:  If  the  Application  uses  TaskMaster,  it  only  needs 
to  make  three  calls  to  support  new  desk  accessories  after  it  has 
loaded  and  started  up  the  proper  tool  sets: 

D  DeskStartup — to  initialize  the  Desk  Manager 

□  FixAppleMenu — to  add  to  the  list  of  NDA's  in  the  Apple  menu 

□  DeskShutdown — to  shut  down  the  Desk  Manager  before  the 
other  tool  sets  are  shut  down 

After  the  FixAppleMenu  call  has  been  made,  TaskMaster 
automatically  handles  opening  NDA's  in  response  to  menu 
selections,  calling  SystemTask  and  SystemClick  when  appropriate. 
If  the  application  sets  up  the  menu  items  correctly,  TaskMaster 
can  even  call  SystemEdit  when  the  user  selects  an  item  from  the 
Edit  menu,  or  close  a  desk  accessory  in  response  to  the  user's 
selecting  Close  from  the  File  menu. 

♦  HodgePodge.-  The  three  calls  listed  above  are  in  the  routines 
StartUpTools,  SetUpMenus,  and  ShutDownTools. 

Without  TaskMaster:  Applications  that  do  not  use  TaskMaster 
must  take  the  following  steps  to  support  new  desk  accessories. 

1.  Call  DeskStartup  to  start  up  the  Desk  Manager. 

2.  Call  FixAppleMenu  to  add  to  the  list  of  NDA's  in  the  Apple  menu. 

3-  Call  OpenNDA  when  the  user  selects  an  NDA  from  the  Apple 
menu. 

4.  Call  SystemTask  frequently  (at  least  every  time  through  the 
event  loop). 

5.  Call  SystemClick  when  a  mouse-down  event  occurs  in  a  system 
window. 

6.  Call  SystemEdit  when  a  desk  accessory  is  active  and  the  user 
selects  Undo,  Cut,  Copy,  Paste,  or  Clear  from  the  Edit  menu. 

If  you  want  to  write  a  new  desk  7.  Close  the  desk  accessory  when  the  user  selects  Close  from  the 

ofCtn?sSbookNDA)'  ^  Chapter  8  File  menu-  You  can  use  CloseNDA  or  CloseNDAbyWinPtr  to  do 

this. 

8.  Call  DeskShutdown  to  shut  down  the  Desk  Manager. 
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Cutting  and  pasting 

An  important  part  of  the  convenience  provided  by  desktop 
applications  is  the  ability  they  give  the  user  to  transfer  and  copy 
fragments  of  text  or  graphics  within  a  document,  or  from  one 
document  to  another. 

The  Scrap  Manager  is  the  tool  set  that  lets  an  application  handle 
cutting  and  pasting  of  the  desk  scrap.  From  the  user's  point  of 
view,  all  data  that's  cut  or  copied  resides  in  the  Clipboard.  The 
Cut  command  deletes  data  from  a  document  and  places  it  in  the 
Clipboard;  the  Copy  command  copies  data  into  the  Clipboard 
without  deleting  it  from  the  document.  The  Paste  command — 
whether  applied  to  the  same  document  or  another,  in  the  same 
application  or  another — inserts  the  current  contents  of  the 
Clipboard  at  a  specified  place.  See  Figure  5-3. 

An  application  that  supports  cutting  and  pasting  may  also  provide 
a  Clipboard  window  for  displaying  the  current  contents  of  the 
scrap;  it  may  show  the  Clipboard  window  at  all  times  or  only  when 
requested  via  the  toggled  command  Show  (or  Hide)  Clipboard. 

♦  Note:  The  Scrap  Manager  is  designed  to  transfer  small  amounts 
of  data;  attempts  to  transfer  very  large  amounts  of  data  may  fail 
from  lack  of  memory. 


Desk  scrap 


Clipboard  window 


Documents 

Figure  5-3 

The  Clipboard  and  the  desk  scrap 
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The  desk  scrap  Is  usually  suited  in  memory,  but  can  be  scored  en 
disk  (in  the  file:  ct.tp board  in  the  SYSTEM  subdirectory  of  the 
boot  volume)  if  there's  net  enough  room  for  it  in  memory.  The 
Desk  Manage*  keeps  I  rack  of  whether  the  scrap  is  in  memory  or 
on  [he  disk,  so  you  don'i  have  to  worry  about  loading  it  first, 

The  uaiure  of  the  data  to  be  transferred  varies.  according  to  the- 
application:  a  word  processor  handles  forma  lied  text;  a  graphics 
application  handles  pictures.  The  Scrap  Manager  allows  for  a 
variety  of  data  types,  and  provides  a  mechanism  w'nereby 
3 ppli cations  have  seme  control  over  hew  much  information  is 
retained  when  data  is  transferred. 

Desk  scrap  data  types 

From  the  user's  point  of  view  there  can  be  only  one  thin#  in  the. 
Clipboard  at  a  time,  but  the  application  may  store  more  than  one 
version  of  the  information  in  the  scrap:  each  representing  the 
same  Clipboard  contents  in  a  different  form.  For  example,  text  cut 
from  a  word  processor  document  may  be  stored  in  the  desk  scrap 
both  as  text  and  as  a  QuickDraw  II  pic!  u  re. 

Why  would  an  application  want  to  do  tills?  Applications  like  to 
keep  Information  in  Jheir  own  haemal  format,  but  they  also  wsiiC 
to  he  able  to  communicate  via  the  Clipboard  with  other 
applicalions   When  a  user  cms  or  copies  something  to  the 
Clipboard,  the  application  can  put  it  there  two  different  ways: 
n  The  internal  way  so  that  a  subsequent  paste  (within  the  same 

application)  can  he  easily  handled.  Precisely  the  information 

needed  by  the  application  can  be  transferred, 
a  The  public  way  so  that  if  the  user  tries  to  paste  it  into  anoihej 

application  or  desk  accessory,  the  other  application  can  at  least 

deal  with  it,  even  if  some  information  might  be  his  I.. 

There  arc  two  defined  public  scrap  types:  text  and  picture. 
Applications  must  wrile  at  least  one  of  these  standard  types  of 
daia  to  the  desk  scrap,  and  must  be  able  to  read  boih  types. 

Using  the  Scrap  Manager 

If  your  application  support*  display  of  the  Clipboard,  you  shouid 
Call  the  nesk  Manager  each  time  through  your  main  event  bop  to 
see  if  the  Clipboard  window  needs  to  he  updated. 

When  a  Cut  or  Copy  command  is  given,  use  the  appropriate  Desk 
Manager  calis  to  write  the  cut  or  copied  data  to  I  he  desk  scrap. 


i  id  nhflntrtr  *v  I  iTinn  f+ir-i  TririlKriii  t  nil 


When  a  Paste  command  is  given,  use  other  Desk  Manager  calls  to 
access  the  particular  type  of  data  in  the  desk  scrap  that  you  want, 
and  to  get  information  about  the  data. 

♦  Edit  menu:  The  user  accesses  the  desk  scrap  through  the  Edit 
menu.  Whether  or  not  your  application  supports  cutting  and 
pasting,  it  must  include  an  Edit  menu.  Desk  accessories  may 
need  it. 

♦  HodgePodge:  HodgePodge  does  not  support  cutting  and 
pasting.  It  has  an  Edit  menu,  but  all  items  are  initially  dimmed 
(disabled). 


Setting  up  a  private  scrap 

If  your  application  defines  its  own  private  type  of  data,  or  if  very 
large  amounts  of  data  might  be  cut  and  pasted,  you  may  want  to 
set  up  a  private  scrap  for  this  purpose.  A  private  scrap  can  have 
any  format,  because  no  other  application  will  use  it.  Your 
application  must,  however,  be  able  to  convert  data  between  the 
format  of  its  private  scrap  and  the  format  of  the  desk  scrap. 

If  you  use  a  private  scrap,  be  sure  that  the  right  data  is  always 
pasted  when  the  user  gives  a  Paste  command.  The  right  data  is 
whatever  was  most  recently  cut  or  copied  from  any  application  or 
desk  accessory.  Make  sure  also  that  the  Clipboard,  if  visible,  always 
shows  the  current  data.  You  should  copy  the  contents  of  the  desk 
scrap  to  your  private  scrap  at  application  startup  and  whenever  a 
desk  accessory  (NDA)  is  deactivated.  When  your  application  quits 
or  when  a  desk  accessory  is  activated,  you  should  copy  the 
contents  of  your  private  scrap  to  the  desk  scrap. 

♦  LineEdit:  The  LineEdit  scrap  is  a  private  scrap  for  applications 
that  use  LineEdit.  LineEdit  provides  routines  for  accessing  this 
scrap;  you'll  need  to  transfer  data  between  the  LineEdit  scrap 
and  the  desk  scrap  so  that  the  Clipboard  will  always  be  current. 

♦  Scrap  too  large:  If  your  application  has  problems  copying  one 
scrap  to  another,  it  should  alert  the  user.  If  the  desk  scrap  is  too 
large  to  copy  to  the  private  scrap,  the  user  may  want  to  leave 
the  application  or  proceed  with  an  empty  Clipboard;  if  the 
private  scrap  is  too  large  to  copy  to  the  desk  scrap,  the  user 
may  want  to  stay  in  the  application  and  cut  or  copy  something 
smaller. 
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Communicating  with  files  and  devices 

The  Apple  IIGS  Toolbox  includes  several  tool  sets  that  handle 
input/output  functions.  They  include 

□  Standard  File  Operations  Tool  Set 

□  Print  Manager 

□  Apple  Desktop  Bus  Tool  Set 

□  Text  Tool  Set 

Using  these  tool  sets  makes  your  application  easier  to  write  and 
ensures  a  uniform  user  interface.  Almost  every  application  needs 
the  Standard  File  Operations  Tool  Set  and  the  Print  Manager; 
fewer  programs  need  the  Apple  Desktop  Bus  Tool  Set  or  the  Text 
Tool  Set. 


Accessing  files 

The  Standard  File  Operations  Tool  Set  provides  the  standard  user 
interface  for  selecting  a  file  to  be  opened  or  saved.  The  tool  set 
displays  dialog  boxes  that  allow  the  user  to  open  and  save  a  file 
on  a  disk  in  any  drive,  and  change  disks  in  a  drive.  The  user  is 
completely  freed  from  having  to  know  how  the  operating  system 
handles  those  tasks. 

Before  you  make  calls  to  the  Standard  File  Operations  Tool  Set,  it 
must  be  loaded  and  started  up.  If  you  think  it  may  not  be  needed 
every  time  the  program  is  run,  you  can  choose  to  load  the  tool  set 
only  when  you  need  to  present  the  dialog  boxes. 


The  HodgePodge  routine 
OpenFilter.  listed  under  "The 
ProDOS  File  System"  in  Chapter  6. 
Is  an  example  of  how  an 
application  can  filter  file  types  in 
Its  Open  File  dialog  box 


Opening  a  file 

When  the  user  makes  a  request  to  open  a  file,  your  application 
calls  the  SFGetFile  routine  to  present  the  standard  Open  File 
dialog  box  (Figure  5-4)  and  retrieve  the  filename.  SFGetFile  allows 
you  to  specify  where  the  standard  dialog  box  will  be  placed  on 
the  screen,  to  specify  the  prompt  at  the  top  of  the  box,  and  to 
select,  or  filter,  the  types  of  files  to  be  displayed  in  the  box.  The 
routine  does  not  allow  you  to  modify  the  appearance  of  the  box; 
if  you  wish  to  construct  your  own  custom  dialog  box,  another 
routine  is  available. 
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AskUser  is  in  the  source  file 
PAINT.PAS. 


Load  which  picture: 
©  /HODGEPODGE/ 

) 

CD  HP.ASM 
CD  HP.CC 
€D  HP.PflS 
DPICl 

0 

C 

Disk 

C 

Open 

1 

( 

) 

i)5»s& 

DPIC2 

D  mm 

D  UMM.t 

o 

c 

Cancel 

) 

Figure  5-4 

The  Open  File  dialog  box 

In  HodgePodge,  the  opening  of  a  file  is  initiated  when  the  user 
chooses  Open  from  the  File  menu.  That  menu  choice  causes  the 
execution  of  the  routine  DoOpenltem,  which  calls  OpenWindow, 
described  in  Chapter  4.  When  opening  a  picture  file  rather  than  a 
font  window,  OpenWindow  calls  AskUser,  the  routine  that  uses 
Standard  File  Operations  to  select  which  file  to  open.  AskUser 
looks  like  this: 


function     AskUser:    Boolean; 

war  ourTypeList:    TypeListPtr; 

begin 


SFGatFile ( 


20,20, 

'Load  wich  picture: 

SOpenFilter, 

TypeListRecPtr(O) , 

myReply) ; 


AskUser  :=  FALSE; 
if  myReply . good  then 
if   LoadOne  then 
AskUser  :=  TRUE; 
end; 


{begin  AskUser...} 

{a  record  that  lists  file  types: 
defined  by  Std.  File  Operations} 


{Call  up  the  dialog  box...} 
{upper-left  corner  =  20,20} 
{=  message  to  user} 
{OpenFilter  screens  file  types} 
{NIL  ptr — show  all  file  types} 
{place  the  results  here} 

{initialize  this  function} 
{if  SFGetFile  not  cancelled..} 
{...and  if  the  file  opens  OK...} 
{AskUser  completes  successfully} 
{End  of  AskUser} 
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The  complete  sequence  of 
routines  that  execute  when  a  file 
is  opened  is  diagrammed  in 
Appendix  D. 


AskUser  calls  LoadOne,  which  allocates  the  memory  for  and 
actually  opens  the  requested  file  by  making  Memory  Manager 
and  ProDOS  16  calls.  SFGetFile  calls  OpenFilter,  a  routine  that 
controls  which  types  of  files  are  displayed  in  the  dialog  box  and 
how  they  are  highlighted.  LoadOne  and  OpenFilter  are 
described  in  Chapter  6,  under  "The  ProDOS  File  System." 


Saving  a  file 

When  the  user  makes  a  request  to  save  a  file,  use  the  SFPutFile 
routine  to  present  the  standard  Save  File  dialog  box  (Figure  5-5). 
SFPutFile  allows  you  to  specify  where  the  standard  dialog  box  will 
be  placed  on  the  screen,  to  specify  the  prompt  at  the  top  of  the 
box,  and  to  specify  the  maximum  number  of  characters  the  user 
may  type.  If  you  wish  to  construct  your  own  custom  dialog  box, 
you  use  another  routine. 


DoSaveltem  is  in  the  source  file 
PAINT.PAS. 


©  /HODGEPODGE/ 

Tree.  illK  OUt  Or  oL'Uk. 

C       Disk    J 

D  fWWMU 
CD  HP.flSM 
CD  HP.CC 
CD  HP.PflS 
D  PJC1 
D  PIC2 

C  New  Folder  1 

(      Close      ) 

Save  which  picture: 

4      Save       | 

an 

C     Cancel     1 

Figure  5-5 

The  Save  File  dialog  box 

In  HodgePodge,  DoSaveltem  is  executed  when  the  user  selects 
Save  As  from  the  File  menu.  (CheckFrontW  makes  sure  that  Save 
As  is  enabled  only  when  a  picture  window  is  in  front,  because  only 
picture  windows  can  be  saved.)  DoSaveltem  first  calls  SFPutFile 
to  bring  up  the  standard  SaveFile  dialog  box,  and  then  calls 
SaveOne,  which  saves  the  contents  of  the  specified  window  to  disk. 
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procedure  DoSaveltem; 


{begin  DoSaveltem...} 


var         theWindow        :    GrafPortPtr; 
myDataHandle :    WindDataH; 
i  :    Integer; 

begin 

theWindow  :=  FrontWindow; 

myDataHandle    :=  WindDataH ( 

GetWRef Con (theWindow) )  ; 
SFPutFile  ( 

20,20, 

1  Save  which  picture : ' , 

myDataHandle"" .name, 

15, 

myReply)  ; 

if  myReply.good  then 
begin 
WaitCursor; 
SaveOne (myDataHandle"" .pict) ; 

with   myDataHandle" "  do 
begin 
name   :=  myReply. fileName; 
menuStr : =  Concat ( ' = ' , 

myReply . f ileName, 
'\N', 

IntToString(menuID) , 
' \0 . ' ) ; 
for  i    :=  firstWind  to  lastWind  do 
if  WindowList [i]    -  theWindow   then 
Leave; 
SetMItam  (MenuStr, 

FirstWindltem+i)  ; 
end; 

SetWTitle (myDataHandle"" .name, theWindow)  ; 
CalcMenuSize(0, 0, WindowsMenuID) ; 
InitCursor; 

end; 

end; 


{pointer  to  a  window} 

{handle  to  our  window-data  record} 


{Get  a  pointer  to  the  front  window} 
{Get  a  handle  to  the  window-data...} 
{...record  for  the  window} 
{Bring  up  the  Save  File  dialog...} 
{...at  location  (20,20)...} 
(...with  this  prompt  string...} 
{...default  =  current  filename...} 
{...allow  15  characters  in  name...} 
{...put  answers  in  Reply  record — 
format  specified  by  Std.  File} 

{If  user  doesn't  cancel...} 
{Put  up  the  watch  cursor  and..} 
{...save  the  file  to  disk.} 

{Update  our  window-data  record:} 

{Update  the  window  name} 
{Make  a  new  menu  string...} 


{Go  through  the  window-pointer  list:} 
{If  this  window  is  the  one...} 
{...exit  from  this  loop} 

{Change  menu  name  to  new  window} 
{end  updating  window-data  record} 

{Update  window  name  to  filename) 
{Resize  menu  for  new  window  name} 
{go  back  to  arrow  cursor} 
{end  of  IF  myReply . good=TRUE } 

{End  of  DoSaveltem} 


The  disk  writing  is  done  by  the  routine  SaveOne.  SaveOne  is 
described  under  "The  ProDOS  File  System"  in  Chapter  6. 

Don't  forget  to  shut  down  the  Standard  File  Operations  Tool  Set 
after  you  have  finished  using  it — either  right  afterward,  or  with  the 
other  tool  sets  at  application  shutdown.  If  you  wish,  you  can  also 
unload  the  tool  set  from  memory  and  thus  save  space. 

♦  Note:  If  you  choose  to  unload  the  Standard  File  Operations  Tool 
Set,  be  sure  to  reload  it  before  making  its  startup  call  again. 
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Printing 

The  Print  Manager  is  an  Apple  IIGS  tool  set  that  allows  you  to  use 
standard  QuickDraw  II  routines  to  print  text  or  graphics.  The  Print 
Manager  calls  a  printer  driver  to  do  the  specific  printing  tasks,  so 
your  application  doesn't  need  to  know  what  kind  of  printer  is 
connected  to  the  computer.  However,  the  Print  Manager  also 
includes  low-level  calls  to  the  printer  drivers  so  that  you  can 
implement  alternate,  low-level  printing  routines. 

An  application  that  supports  printing  must  have  three  items  in  its 
File  menu:  Choose  Printer,  Page  Setup,  and  Print.  Choosing  these 
items  brings  up  dialog  boxes  that  allow  the  user  to  specify  how  a 
document  will  be  printed. 

Choosing  a  printer 

When  the  user  selects  the  Choose  Printer  item,  the  Choose  Printer 
dialog  box  is  displayed  (Figure  5-6).  It  lets  the  user  select  a 
destination  device  from  among  the  printer  drivers  on  the  system 
disk.  The  Choose  Printer  dialog  box  also  lets  the  user  pick  which 
port  or  slot  the  device  is  connected  to,  from  among  the  port 
drivers  on  the  system  disk. 


Choose  Printer                              vl.2 

Printer  type: 

Printer  port: 

IMAGEWRITER 

j>l 

timmm 

1> 

| LASERWRITER 

MODEM 
PRINTER 

o 

o 

c 

:ar 

cel}(£     OK     ]() 

Figure  5-6 

The  Choose  Printer  dialog  box 


166 


rhnntar  £.■  I  kin/-.  +K,-,  T-,~ii-., 


DoChooserltem  is  in  the  source 
file  PRINT.PAS. 


If  the  AppleTalk  network  is  installed  and  the  AppleTalk  selection  is 
made  in  the  dialog  box,  the  network  is  scanned  for  the  names  of 
all  connected  printers.  If  one  or  more  printers  of  the  chosen  type 
are  available  on  the  network,  an  additional  dialog  box  appears  so 
that  the  user  can  select  one. 

♦  Macintosh  programmers:  On  the  Apple  IIGS,  the  Choose 
Printer  function  is  part  of  the  Print  Manager,  rather  than  part 
of  the  Chooser  desk  accessory  as  on  the  Macintosh. 

The  HodgePodge  routine  that  brings  up  the  Choose  Printer 
dialog  box  is  called  DoChooserltem.  It  is  called  from  DoMenu, 
when  the  user  selects  Choose  Printer  from  the  File  menu. 


procedure  DoChooserltem; 

rar         dummy:    Boolean; 

begin 

dummy    :=   PrChooser; 

and; 


{begin  DoChooserltem...} 

{returned  value  is  unimportant  here} 


{Bring  up  dialog  box — that's  it!} 
{End  of  DoChooserltem} 


Making  page  settings 

When  the  user  selects  the  Page  Setup  item,  a  Style  dialog  box  is 
displayed  (Figure  5-7).  It  allows  the  user  to  specify  formatting 
information,  such  as  the  page  size  and  printing  orientation.  This 
information  is  not  changed  frequently  and  is  usually  saved  with 
the  document.  The  LaserWriter  offers  two  style  options 
unavailable  for  the  ImageWriter:  smoothing  of  bitmapped  fonts, 
«nd  font  substitution. 
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IMflGEWRITER/flPPLETRLK 


vl.3 


Paper: 
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DoSetupltem  is  in  the  source  file 
PRINT.PAS. 
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Figure  5-7 

Style  dialog  boxes 


I 


Page  setup  in  HodgePodge  is  handled  by  the  routine 
DoSetupltem,  called  from  DoMenu  when  the  user  selects  Page 
Setup  from  the  File  menu.  DoSetupltem  calls  the  Print  Manager 
routine  PrStlDialog,  passing  it  a  handle  to  a  print  record.  The 
print  record  has  been  allocated  and  initialized  by  the  routine 
SetUpDefault,  called  at  startup. 
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procedure  DoSetupItem; 

var         dummy:    Boolean; 

begin 

dummy    :=  PrStlDialog (printHndl)  ; 

end; 


{begin  DoSetupItem...} 

{function  result  unimportant  here} 


{Call  up  the  dialog,  pass  it  the 
handle  to  our  print  record} 
{End  of  DoSetupItem} 


Printing 

When  the  user  chooses  to  print  a  document,  usually  by  making  a 
selection  on  the  File  menu,  the  Job  dialog  box  is  displayed  (Figure 
5-8).  The  Job  dialog  box  lets  the  user  select  print  quality,  page 
range,  number  of  copies,  and  other  printer-specific  information. 
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Figure  5-8 

Job  dialog  boxes 
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DoPrintltem  is  in  the  source  file 
PRINT. PAS. 


The  Print  Manager  automatically  gives  you  a  QuickDraw  II 
GrafPort  when  you  open  a  document  for  printing.  You  then  print 
text  and  graphics  by  drawing  into  this  port  with  QuickDraw  II  calls, 
just  as  if  you  were  drawing  on  the  screen.  The  Print  Manager 
installs  its  own  versions  of  QuickDraw  IPs  low-level  drawing 
routines  in  this  GrafPort,  causing  your  higher-level  QuickDraw  II 
calls  to  drive  the  printer  instead  of  drawing  on  the  screen. 

The  HodgePodge  routine  that  prints  files  is  DoPrintltem,  called 
from  DoMenu  when  the  user  selects  Print  from  the  File  menu. 
DoPrintltem  calls  the  routine  PrJobDialog  to  bring  up  the  Job 
dialog  box,  and  then  calls  DrawTopWindow  to  print  the  file: 


procedure  DoPrintltem; 

var  prPort    :  GrafPortPtr; 

theWindow:  GrafPortPtr; 

begin 

theWindow    :=  FrontWindow; 
if  theWindow  <>  NIL  then 

if  PrJobDialog (printHndl)    then 
begin 

WaitCursor; 
prPort    :-  PrOpenDoc (printHndl, NIL); 

PrOpenPage (prPort, NIL) ; 
DrawTopWindow (theWindow) ; 
PrClosePage (prPort) ; 

PrCloseDoc (prPort) ; 
PrPicFile (printHndl , NIL, NIL)  ; 
InitCursor; 
end; 


end; 


{begin  DoPrintltem...) 

{pointer  to  a  printing  GrafPort} 
{window  pointer} 


DrawTopWindow  is  in  the  source 
file  PRINT.PAS. 


{Get  a  pointer  to  the  front  window} 
{If  there  IS  a  window  open...} 
{..bring  up  the  dialog  box;  if...} 
{...the  user  doesn't  cancel...} 
{put  up  the  watch  cursor...} 
{open  a  printing  GrafPort..  ) 

{begin  a  new  (&  only)  page...} 
{draw  the  contents  of  the  page...} 
{...close  the  page} 

{...close  the  GrafPort} 

{...print  the  spooled  file} 

{...and  restore  the  regular  cursor} 

{end  of  printing} 

{end  of  IF  a  window  is  open} 

{End  of  DoPrintltem} 

See  "Using  the  Print  Manager,"  later  in  this  section,  for 
explanations  of  some  of  the  Print  Manager  calls  that 
DoPrintltem  makes. 

DoPrintltem  calls  the  subroutine  DrawTopWindow,  which  does 
the  actual  drawing  in  the  printer  GrafPort.  DrawTopWindow  acts 
no  differently  than  if  it  were  drawing  to  the  screen;  it  calls  either 
ShowFont  or  Paint  It,  depending  on  what  type  of  window  is  to 
be  printed: 
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procedure  DrawTopWindow (TheWindow:WindowPtr) ; 

var         myDataHandle :    WindDataH; 

begin 

myDataHandle    : =  WindDataH ( 

GetWRef Con (TheWindow) )  ; 

with  myDataHandle A/s   do 
if  Flag  =   0   then 

Paintlt (pict) 
else 

ShowFont  (theFont, isMono) ; 
end; 


(begin  DrawTopWindow...} 
{handle  to  window-data   record} 


{Get   a  handle  to  the  window's... 
{...window-data   record} 

{If  it's   a  picture  window...} 
{paint  the  picture  w/this  handle} 
{But   if  it's  a   font   window...} 
{draw  text  w/this   font    &    style} 
{End  of  DrawTopWindow} 


The  structure  of  a  print  record  is 
shown  In  the  Apple  IIGS  Toolbox 
Reference. 


Important 


Using  the  Print  Manager 

Print  records:  Before  you  can  print  a  document,  you  need  a  valid 
print  record.  The  print  record  describes  information  such  as  page 
dimensions  and  resolution.  You  can  either  use  an  existing  print 
record  (for  instance,  one  saved  with  a  document)  or  create  one 
through  Print  Manager  calls.  HodgePodge  uses  the  same  print 
record  for  all  documents.  That  record  can  be  modified  by  the 
user  through  the  Style  and  Job  dialog  boxes. 

♦  Note:  Whenever  your  application  saves  a  document,  it  should 
save  an  appropriate  print  record  with  the  document.  This  sets 
up  the  printing  parameters  for  the  document  so  that  they  can 
be  used  the  next  time  the  document  is  printed. 

In  most  instances  your  application  should  not  directly  change  the 
data  in  the  print  record— it  should  use  the  standard  dialog  routines 
for  changing  this  information.  Attempting  to  set  certain  values 
directly  in  the  print  record  can  produce  unexpected  results. 

Draft  and  spool  printing:  There  are  two  basic  methods  of 
printing  documents:  draft  and  spool. 

In  draft  printing,  your  QuickDraw  II  calls  are  converted  directly 
into  command  codes  the  printer  understands,  which  are  then 
immediately  used  to  drive  the  printer.  The  LaserWriter  always  uses 
draft  printing,  because  the  QuickDraw  II  calls  are  translated 
immediately  into  PostScript  commands.  The  ImageWriter  and 
other  nonintelligent  dot  matrix  printers  are  written  to  in  draft 
mode  for  text  only.  High-quality  pixel  images  are  produced  by 
spool  printing. 
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Compare  this  sequence  of  calls 
with  the  listing  of  the  HodgePodge 
routine  DrawTopWindow,  earlier 
in  this  section. 


In  spool  printing  the  Print  Manager  processes  your  printing 
requests  in  two  steps.  First  it  writes  out  {spools)  a  representation  of 
your  document's  printed  image  to  a  disk  file  or  to  memory. 
Second,  this  information  is  converted  into  a  bit  image  and 
printed.  This  method  is  used  to  print  graphics  on  the 
ImageWriter. 

The  printing  loop:  To  print  a  document,  you  call  the  following 
routines: 

1.  PrOpenDoc,  which  returns  a  pointer  to  the  GrafPort  to  be  used 
for  printing 

2.  PrOpenPage,  which  starts  each  new  page  (reinitializing  the 
GrafPort) 

3.  QuickDraw  routines,  for  drawing  the  page  into  the  port  created 
by  PrOpenDoc 

4.  PrClosePage,  which  terminates  the  page 

5.  PrCloseDoc,  at  the  end  of  the  entire  document,  to  close  the 
GrafPort  being  used  for  printing 

6.  PrPicFile,  to  print  the  spooled  document 

Steps  2  through  4  are  the  printing  loop  itself;  they  are  repeated  for 
as  many  pages  as  are  printed.  Each  page  is  either  printed 
immediately  (draft  printing)  or  written  to  disk  or  to  memory 
(spool  printing).  Your  application  may  inspect  the  print  record  to 
see  whether  spooling  was  done,  but  it  doesn't  have  to.  The  proper 
method  is  always  selected  automatically,  and  PrPicFile  is  executed 
only  if  needed. 

You  should  check  for  errors  after  each  Print  Manager  call.  If  an 
error  occurs  and  you  cancel  printing  (or  if  the  user  aborts 
printing),  be  sure  to  exit  properly  from  the  printing  loop  so  tha 
all  files  are  closed  correctly — that  is,  be  sure  that  every 
PrOpenPage  is  matched  by  a  PrClosePage,  PrOpenDoc  is 
matched  by  PrCloseDoc,  and  PrPicFile  is  still  called. 


Note:  The  maximum  number  of  pages  in  a  spool  file  is  16,382. 
If,  for  some  strange  reason,  you  need  to  print  more  than  16,382 
pages  at  one  time,  just  repeat  the  printing  loop. 
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Transfer  modes  are  discussed 
under  "Drawing  to  the  Screen." 
Chapter  3. 


in 


QuickDraw  II  consequences  and  limitations:  Even  though  you 
print  by  making  QuickDraw  calls,  remember  that  printing  to  paper 
is  not  really  the  same  as  drawing  to  the  screen.  Clipping  regions 
and  character  spacings  don't  translate  exactly.  Erasing,  of  course, 
can't  be  done  on  a  printer.  Some  transfer  modes  and  some 
drawing  routines  don't  work  on  a  LaserWriter.  For  more 
information  about  optimizing  your  printing  code,  see  the  Apple 
IIGS  Toolbox  Reference  and  the  LaserWriter  Reference. 

Background  procedure:  An  optional  background  procedure 

runs  whenever  the  Print  Manager  has  directed  output  to  the 
printer  and  is  waiting  for  the  printer  to  finish.  It  is  typically  a 
dialog  box  that  informs  the  user  that  a  print  job  is  in  progress, 
and  allows  the  user  the  option  of  canceling  it. 

If  you  don't  designate  a  background  procedure,  the  Print  Manager 
uses  a  default  procedure  for  canceling  printing:  the  default 
procedure  just  polls  the  keyboard  and  sets  a  Print  Manager  error 
code  if  the  user  presses  Apple-Period.  If  you  use  this  option,  you 
should  display  a  dialog  box  during  printing  to  inform  the  user 
that  the  Apple-Period  option  is  available. 


The  multiple-segment  sample 
program  listed  under  "Creating 
Segmented  Code:  Three 
Examples"  in  Chapter  7  includes 
calls  to  the  Text  Tool  Set. 


The  Pascal  and  BASIC  character 
device  drivers  are  discussed  in 
the  Apple  IIGS  Firmware 
Reference 


Sending  text  to  Apple  II  character  devices 

If  you  are  writing  a  native-mode  Apple  IIGS  application  but  don't 
want  to  use  QuickDraw  II  and  the  graphic  desktop  interface,  you 
may  need  the  Text  Tool  Set.  It  provides  an  interface  between 
Apple  II  character  device  drivers,  which  must  be  executed  in 
emulation  mode,  and  new  applications  running  in  native  mode.  It 
also  provides  a  means  of  redirecting  I/O  through  RAM -based 
drivers.  The  Text  Tool  Set  makes  it  possible  to  deal  with  the  text 
screen  without  switching  65816  processor  modes  and  moving  to 
bank  zero.  Dispatches  to  RAM-based  drivers  still  occur  in  full 
native  mode. 

The  Text  Tool  Set  has  global  routines  that  are  used  to  set  or  read 
the  current  global  parameters  used  by  RAM  and  the  Pascal  and 
BASIC  text  drivers.  The  tool  set  also  has  I/O  directing  routines 
that  direct  I/O  from  the  tool  set  to  a  specific  type  of  character 
device  driver,  or  request  information  about  the  directing  of  a 
specific  I/O  driver.  Finally,  the  tool  set  has  text  routines  that 
interface  with  any  BASIC,  Pascal  1.1,  or  RAM-based  character 
device  driver.  See  "Text  Tool  Set"  in  the  Apple  IIGS  Toolbox 
Reference  for  more  details. 
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Communicating  with  Apple  Deskfop  Bus  devices 

The  Apple  Desktop  Bus  (ADB)  is  a  hardware  channel  and  a 
protocol  for  connecting  input  devices,  such  as  keyboards  and 
mouse  devices,  with  personal  computers.  The  personal  computer 
is  considered  to  be  the  host  during  the  communication,  and 
controls  the  communication  on  the  bus  by  issuing  ADB 
commands  to  the  devices. 

The  Apple  Desktop  Bus  Tool  Set  sends  commands  and  data 
between  the  Apple  Desktop  Bus  microcontroller  and  the  rest  of 
the  system.  Typically,  the  tool  set  is  used  to  control  ADB  activity, 
but  other  commands,  which  are  used  by  diagnostic  routines  and 
the  Control  Panel,  are  available. 

Most  applications  have  no  need  to  use  the  ADB  Tool  Set. 
However,  if  your  program  needs  to  modify  the  system's  interface 
with  the  mouse,  keyboard,  or  other  ADB  device,  the  ADB  Tool  Set 
is  indispensable. 

More  details  about  the  bus  can  be  found  in  the  Apple  IIGS 
Firmware  Reference  and  the  Apple  IIGS  Hardware  Reference.  The 
tool  set  is  described  under  "Apple  Desktop  Bus  Tool  Set"  in  the 
Apple  IIGS  Toolbox  Reference. 


Making  sounds 

The  Apple  IIGS  has  a  very  advanced  sound-generation  system, 
capable  of  creating  and  reproducing  complex  music,  sound 
effects,  and  speech.  Sound  tools  at  several  levels  give  you  access 
to  the  sound  hardware  and  make  music  generation  easy. 


The  sound  hardware 

The  Apple  IIGS  sound  hardware  supports  two  sound-generation 
methods.  In  the  first  method,  which  replicates  the  Apple  He  sound 
capabilities,  an  application  toggles  a  soft  switch  which  in  turn 
generates  clicks  in  a  speaker.  The  application  can  control  the  rate 
of  clicking  and  the  volume  of  the  speaker. 
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The  second  method  uses  a  digital  oscillator  chip  (DOC)  and  the 
rest  of  the  sound  hardware,  as  diagrammed  in  Figure  5-9:  64K  of 
dedicated  RAM,  the  Sound  GLU  (general  logic  unit),  the  analog 
section,  and  the  sound  connector. 


IIGS  I/O 


Connector 


For  further  information  on  the  DOC. 
see  the  Apple  IIGS  Hardware 
Reference 


Figure  5-9 

Sound  hardware  block  diagram 

The  sound  GLU  acts  as  the  I/O  interface  between  the  Apple  IIGS 
system  hardware  and  the  sound  hardware.  The  dedicated  RAM 
stores  the  waveforms  used  for  sound  generation.  From  them  the 
DOC  can  create  sounds  of  practically  any  pitch  and  duration. 

The  analog  section  contains  all  the  circuitry  needed  to  amplify 
and  filter  the  signal  coming  from  the  Sound  GLU  or  the  DOC. 
From  there  the  signal  is  sent  to  the  speaker. 
The  sound  connector  provides  the  connection  to  interface  cards 
that  can  take  the  tones  generated  by  the  DOC  and  modify  them 
further.  Three  examples  of  possible  sound  cards  are 
programmable  filter  cards,  stereo  interface  cards,  and  sound 
sampling  cards. 


Oscillators  and  generators 

An  oscillator  is  the  basic  sound-generating  unit  in  the  DOC.  The 
DOC  contains  32  oscillators,  each  of  which  can  function 
independently  from  all  the  other  oscillators. 
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The  System  Failure  Manager  is 
described  under  "Miscellaneous 
Tool  Set"  In  the  Apple  Hgs 
Toolbox  Reference. 


See  "Sound  Tool  Set"  in  the 
Apple  Hgs  Toolbox  Reference  for 
details  on  both  high-level  (free- 
form  synthesizer)  and  low-level 
calls. 


One  of  the  modes  of  the  DOC  is  called  swap  mode.  The  Sound 
Tool  Set  (described  next)  uses  this  mode  to  generate  sounds  In 
swap  mode,  a  pair  (swap  pair)  of  oscillators  forms  a  functional 
unit  called  a  generator.  There  are  15  generators  defined  in  the 
Apple  HGS  sound  system.  The  oscillators  in  a  generator  take  turns 
making  sound,  each  signaling  the  end  of  its  sound  by  generating 
an  interrupt. 

Oscillators  30  and  31  are  reserved  for  system  use  and  should  not 
be  be  used  by  applications.  If  an  interrupt  is  generated  by 
oscillator  30  or  31  it  is  a  fatal  error-a  sound  interrupt  is  reported 
to  the  System  Failure  Manager,  which  halts  execution. 


The  Sound  Tool  Set 

The  Sound  Tool  Set  gives  you  the  ability  to  access  the  sound 
hardware  without  having  to  know  specific  hardware  I/O  addresses 
Sound  Tool  Set  calls  can  be  divided  into  two  groups:  hieh-level 
and  low-level. 

High-level  calls  constitute  the  free-form  synthesizer.  Calls  to  the 
free-form  synthesizer  are  made  through  the  normal  tool  call 
mechanism,  with  parameters  being  passed  to  and  from  the  called 
routines  on  the  stack.  With  high-level  calls  you  can 

□  write  multibyte  sound  data  to  and  read  it  from  DOC  RAM 

□  get  or  set  the  volume  of  individual  generators 

D  start  and  stop  sound  on  an  individual  generator 

Low-level  routines  read  from  and  write  to  the  DOC  hardware 
registers  and  individual  DOC  RAM  locations.  Unlike  the  other 
Sound  Tool  Set  routines,  which  use  the  stack  to  pass  parameters  in 
the  normal  tool  call  fashion,  these  routines  use  registers  to  pass 
parameters  and  are  entered  through  a  jump  table.  The  low-level 
routines  can  move  information  faster  than  the  higher-level  calls 
to  the  free-form  synthesizer,  but  they  do  none  of  the  error 
checking  and  housekeeping  of  the  higher-level  routines 
Furthermore,  if  you  use  the  low-level  routines,  you  will  have  to 
install  your  own  interrupt  handler  to  service  sound  interrupts 
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The  Note  Synthesizer 

The  Note  Synthesizer  gives  your  application  a  convenient  way  to 
play  musical  notes.  You  use  the  Note  Synthesizer  by  making  tool 
calls  to  start  and  stop  individual  notes.  The  general  sequence  of 
calls  is  something  like  this: 

1.  Allocate  an  individual  generator. 

2.  Start  a  note,  with  the  NoteOn  call.  The  call's  parameters  specify 
the  generator  to  play  the  note  on,  the  note's  volume  and  pitch, 
and  what  instrument  to  use.  An  Instrument  is  a  data  structure 
that  specifies  such  parameters  as  the  amplitude  envelope 
(attack  and  decay  shapes),  pitchbend  and  vibrato 
characteristics,  and  the  specific  waveforms  that  characterize  the 
sound  to  be  played. 

3.  Stop  the  note  with  the  NoteOff  call.  When  the  note  stops 
playing,  the  generator  is  automatically  deallocated. 

The  Note  Synthesizer  provides  for  priority  in  allocation  of 
individual  generators.  If  all  generators  are  in  use,  generators 
producing  low-priority  sound  (such  as  notes  trailing  off)  can  be 
"stolen"  to  produce  higher-priority  sounds  (such  as  notes  starting 
up).  Priority  assignment  can  assure  that  there  will  always  be  a 
generator  available  when  a  note  needs  to  be  played. 

♦  Enable  interrupts:  Interrupts  must  be  enabled  in  order  for  the 
Note  Synthesizer  to  function.  Anything  that  disables  interrupts 
(such  as  accessing  a  disk  drive)  will  disrupt  the  sound  being 
played. 


The  Note  Sequencer 

The  Note  Sequencer  is  the  tool  set  that  makes  it  easy  for  you  to 
include  music  in  your  programs.  In  particular,  it  allows  music  to 
be  played  asynchronously,  in  the  background. 

The  Note  Sequencer  builds  upon  the  Note  Synthesizer,  in  that  it 
strings  together  individual  notes  created  by  the  sythesizer. 

You  can  think  of  the  Note  Sequencer  as  a  cross  between  a  player 
piano  and  a  language  interpreter.  A  sequence  is  a  series  of 
commands  that  tell  the  computer  which  notes  to  play  and  when. 
The  Note  Sequencer  plays  back  that  sequence  to  generate  muscial 
sound. 
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MIDI  stands  for  Musical  Instrument 
Digital  Interface,  an  international 
standard  for  electronic  transfer  of 
musical  data. 


Sequences  are  built  up  from  simpler  components.  Individual  basic 
commands  to  the  Sequencer  are  called  items.  Items  typically  turn 
a  note  on  or  off,  or  control  some  aspect  of  the  note's  sound,  such 
as  vibrato.  Items  are  assigned  to  one  or  more  tracks,  to  facilitate 
the  concept  of  multi-instrument  music  and  chords.  A  pattern  is  a 
series  of  items;  the  pattern  groups  those  items  in  terms  of  their 
mutual  timing  relationships. 

A  phrase  is  a  set  of  pointers  to  patterns  or  to  other  phrases. 
Phrases  make  it  easy  to  build  repetitive,  complex  passages  out  of 
simple  patterns.  A  sequence  is  a  top-level  phrase,  one  which 
points  to  patterns  or  other  phrases  but  is  not  pointed  to  by  any 
other  phrases. 

You  play  music  with  the  Sequencer  by  making  a  StartSeq  call.  It 
plays  a  specified  sequence.  In  interrupt  mode,  the  sequence  is 
played  automatically  until  it  finishes.  In  step  mode,  your 
application  can  play  the  sequence  item-by-item.  Step  mode  is 
useful  if  you  need  to  synchronize  the  sequence  with  other  events 
in  your  program. 

♦  Enable  interrupts:  Interrupts  must  be  enabled  in  order  for  the 
Sequencer  to  function.  Anything  that  disables  interrupts  (such 
as  accessing  a  disk  drive)  will  disrupt  the  sound  being  played. 

♦  MIDI:  The  Sequencer  is  not  directly  compatible  with  the  MIDI 
protocol.  If  you  wish  to  communicate  with  a  MIDI  synthesizer 
on  your  Apple  IIGS,  you  will  need  to  install  a  MIDI  interface 
card  or  a  MIDI  serial  adapter  (manufactured  for  the  Macintosh 
Plus).  At  the  time  of  this  writing,  there  are  no  software  tools  to 
allow  the  Note  Synthesizer  or  Sequencer  to  manipulate  MIDI 
data. 


Computing 

If  your  applications  require  mathematical  computations  on  either 
integers  or  floating-point  numbers,  there  are  Apple  IIGS  tool  sets 
that  provide  you  with  fast,  consistent,  and  accurate  algorithms. 
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Integer  Math 

The  Integer  Math  Tool  Set  supports  multiplication  and  division  of 
several  types  of  numbers,  and  also  converts  numbers  from  one 
type  to  another.  The  types  of  numbers  dealt  with  are  these: 

integer  l6-bit  signed  or  unsigned  value 

longint  32-bit  signed  or  unsigned  value 

fixed  32-bit  signed  value  with  16  bits  of  fraction 

frac  32-bit  signed  value  with  30  bits  of  fraction 

extended  80-bit  signed  value  with  64  bits  of  fraction 

♦  Note.-  The  extended  type  really  serves  as  a  pathway  to  the 
Standard  Apple  Numeric  Environment.  See  the  next  section  in 
this  chapter,  "High-Precision  Floating-Point  Math  (SANE)." 

The  Integer  Math  Tool  Set  also  manipulates  Integer  Math  strings, 
which  are  ASCII-string  representations  of  numbers.  An  Integer 
Math  string  consists  of  only  digits  (hexadecimal  or  decimal)  and 
blanks  and  has  no  length  byte  within  it. 

Within  the  tool  set,  there  are  math  routines  and  Integer  Math 
string  routines.  Math  routines  support  multiplication  and  division 
of  integer,  long  integer,  fixed,  and  frac  numbers,  perform  simple 
trigonometric  calculations,  and  convert  from  one  type  of  value  to 
another.  Integer  Math  string  routines  convert  between  a  binary 
value  and  an  ASCII  character  string  representing  that  value.  The 
binary  value  can  be  either  an  integer  or  a  long  integer.  The 
character  string  can  be  in  either  hexadecimal  or  decimal  format. 

Your  application  can  make  use  of  the  Integer  Math  routines  at  any 
time;  the  tool  set  is  always  active.  Furthermore,  the  Integer  Math 
Tool  Set  does  not  rely  upon  the  presence  of  any  other  tool  sets. 


High-precision  floating-point  math  (SANE) 

For  high-precision  calculations  on  floating-point  numbers,  your 
application  should  use  the  Standard  Apple  Numerics 
Environment  (SANE).  SANE  is  a  collection  of  routines  that 
perform  extended-precision  IEEE  arithmetic,  with  elementary 
functions.  SANE  scrupulously  conforms  to  IEEE  standard  754  for 
binary  floating-point  arithmetic  and  to  the  proposed  IEEE 
standard  854,  which  is  a  radix-independent  and  word-length- 
independent  standard  for  floating-point  arithmetic. 
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Additional  information  on  SANE 
routines  is  found  under  "SANE 
Tool  Set"  in  the  Apple  IIGS 
Toolbox  reference 


SANE  provides  sufficient  numeric  support  for  most  application; 
includes 

D  IEEE  types  single  (32-bit),  double  (64-bit),  and  extended  (80- 
bit) 

□  a  64-bit  type  for  large-integer  computations,  as  in  accounting 

□  fundamental  floating-point  operations  (  +  -  *  /  V  rem  ) 

□  comparisions 

□  binary-to-decimal  and  floating-point-to-integer  conversions 

□  scanning  and  formatting  for  ASCII  numeric  strings 

□  logarithmics,  trigonometries,  and  exponentials 

□  compound  and  annuity  functions  for  financial  computations 

□  a  random  number  generator 

□  functions  for  management  of  the  floating-point  environment 

a  other  functions  required  or  recommended  by  the  IEEE 
Standard 

The  Apple  IIGS  SANE  tool  set  matches  the  functions  of  the 
Macintosh  SANE  packages,  and  the  6502  assembly-language  SAN 
software  from  which  it  is  derived. 

The  functions  of  SANE  are  completely  documented  in  the  Apple 
Numerics  Manual,  which  you  will  need  if  you  are  going  to  use  the 
routines  in  your  application. 


Controlling  the  operating  environment 

Many  components  make  up  the  Apple  IIGS  operating 
environment,  the  overall  hardware  and  software  setting  within 
which  application  programs  run.  Several  tool  sets'  principal 
functions  are  to  control  and  modify  that  environment.  You  might 
call  them  low-level  tool  sets,  in  contrast  to  the  higher-level, 
desktop  interface  tools. 

The  Event  Manager,  described  earlier,  and  the  Memory  Managed 
and  System  Loader,  described  in  the  next  chapter,  are  three  of  the 
most  important  tool  sets  in  this  group.  Two  others  are  the 
Miscellaneous  Tool  Set  and  the  Scheduler,  described  here 
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The  Miscellaneous  Tool  Set 

The  Miscellaneous  Tool  Set  is  a  collection  of  several  small  tool 
sets.  Most  of  them  set  or  return  information  about  various  low- 
level  functions  of  the  Apple  IIGS.  Several  other  managers  and  tool 
sets  make  calls  to  the  Miscellaneous  Tool  Set. 

Many  of  the  routines  in  this  tool  set  retrieve  the  address  or  return 
the  value  of  a  given  parameter  so  that  your  program  need  not  rely 
on  fixed  addresses.  Please  use  these  calls  instead  of  directly 
accessing  memory  locations;  there  is  no  guarantee  that  an  address 
being  used  for  something  in  one  version  of  system  software  will 
be  used  the  same  way  in  subsequent  versions. 


Parameter  RAM.  also  known  as 
Battery  RAM.  retains  clock- 
calendar  and  Control  Panel 
Information  when  the  computer 
power  Is  off. 


Tick  count  Is  (approximately)  the 
number  of  60th-second  intervals 
elapsed  since  system  startup. 

For  more  information  about 
Interrupt  sources  and  handlers, 
see  the  Apple  IIGS  Firmware 
Referenceand  theAppleIGS 
ProDOS  16  Reference. 


Groups  of  routines 

a  You  can  use  Battery  RAM  routines  to  write  and  read  data  to 
and  from  parameter  RAM.  Any  data  written  to  parameter 
RAM  will  affect  the  default  system  configuration,  which  will  be 
used  the  next  time  the  system  is  booted. 

□  The  clock  routines  provide  you  with  a  way  to  read  the  current 
time  either  in  hex  or  ASCII  format,  or  set  the  current  time  using 
hex  format.  The  GetTick  routine  reads  the  current  tick  count. 

□  Vector  routines  set  or  return  the  vector  address  for  a  specified 
interrupt  manager  or  handler.  Interrupt  control  routines  allow 
your  application  to  enable  or  disable  certain  interrupt  sources 
and  get  the  current  status  of  those  interrupts. 

□  Address  and  entry  routines  return  the  addresses  and  native- 
mode  entry  points  of  some  important  firmware  parameters  and 
routines. 

□  The  HeartBeat  routines  allow  you  to  install  or  delete  tasks  from 
the  HeartBeat  Interrupt  Task  queue.  Such  tasks  might  include 
controlling  cursor  movement,  or  posting  a  disk-insert  event,  or 
checking  the  stack.  They  are  called  at  some  multiple  of  every 
"heartbeat"  (vertical  blanking  interval),  60  times  a  second. 

n  The  System  Failure  Manager  routine  allows  you  to  customize 
the  system  failure  message.  Thus,  if  the  user  causes  your 
application  to  crash,  you  can  have  the  System  Failure  Manager 
display  a  message  that  gives  the  user  an  idea  of  what  happened. 
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□  The  User  ID  Manager  routines  create  and  delete  the  numbers 
by  which  the  ownership  of  all  allocated  memory  blocks  is 
specified.  Every  program  on  the  Apple  IIGS  has  a  User  ID, 
assigned  by  the  User  ID  Manager;  each  block  that  the  Memory 
Manager  allocates  for  that  program  is  given  the  program's 
User  ID. 

a  The  mouse  routines  allow  your  application  to  directly  set  or  g< 
the  mouse  location.  However,  the  Event  Manager  calls  these 
routines  automatically,  so  most  applications  don't  need  to 
make  the  calls.  If  you're  not  using  the  Event  Manager  or 
TaskMaster,  you  may  need  to  use  the  mouse  routines. 

a  The  PackBytes  routine  packs  data  to  make  a  file  smaller.  This 
can  be  useful  for  such  things  as  graphic  images,  which  would 
ordinarily  take  up  too  much  space  on  disk.  UnPackBytes 
unpacks  the  data  from  the  PackBytes  format. 

Q  The  Munger  routine  allows  your  application  to  manipulate 
strings  easily. 

□  The  SysBeep  routine  causes  the  system  speaker  to  beep. 

"The  Miscellaneous  Tool  Set"  in  the  Apple  IIGS  Toolbox 
Reference  describes  in  detail  all  of  the  above  groups  of  routines. 


The  Scheduler 

The  Scheduler  is  a  tool  set  that  delays  the  activation  of  a  desk 
accessory  or  other  task  until  the  resources  that  the  desk  accessory 
or  task  needs  become  available.  Much  of  the  system  code  is  not 
reentrant;  that  is,  the  code  cannot  be  called  again  while  it  is 
executing.  Because  of  that,  activating  a  desk  accessory  within  non- 
reentrant  code  almost  always  causes  the  system  to  fail.  Thus,  the 
Apple  IIGS  provides  a  Busy  flag  that  the  Scheduler  can  check  to 
discover  if  a  needed  resource  is  busy  or  available. 

To  write  a  typical  application,  you  won't  need  to  use  the 
Scheduler.  Even  if  you  are  writing  a  classic  desk  acccessory  you 
won't  need  to  call  the  Scheduler— the  Desk  Manager  does  it  for 
you.  Perhaps  the  only  time  you  need  to  use  it  is  when  you  are 
writing  interrupt  handlers  that  access  ProDOS  16  or  the  toolbox 
routines.  For  example,  an  application  that  performs  background 
printing  might  need  to  access  the  Scheduler. 
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The  Scheduler  Is  completely  Scheduler  maintains  a  queue  of  tasks  waiting  to  execute,  and 

documented  under  "The  consults  the  Busy  flag  before  dispatching  them.  When  a  non- 

TStocl^eference^  "GS  reentrant  module  is  entered,  your  interrupt  handler  should  set  the 

Busy  flag;  when  exiting  from  the  module,  the  application  should 
clear  the  Busy  flag,  permitting  the  Scheduler  to  execute  any  tasks 
that  have  been  placed  in  its  queue. 

Your  interrupt  handler  should  therefore  check  the  state  of  the 
Busy  flag  before  it  calls  any  system  software.  If  the  word  is 
nonzero,  the  necessary  system  resources  are  not  currently 
available,  and  you  should  add  your  task  to  the  Scheduler's  queue. 
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□  how  to  use  the  ProDOS  16  OUIT  rail  ^  ™ 

another  program   and  rhZ  k  P2SS  execution  to 

again  '  en  bnng  your  Pro8ram  back  to  execute 

D  Z^T1-™^  SPaCG  ^  ^  h°W  to  «  ^  up  for  your 
□  how  to  access  disk  files 

You  do  not  need  detailed  knowledge  of  all  of  rh.c    ,     •      ■ 

to  write  an  application   R,„  -e  ?  these  toPlcs  m  °<*r 


:ute 


deciding  jus,  where  ,olT?n    C°mpU,ers  memt">'  ™P  and 

may  interfere  with  the  effidem  ni    f  8  S°'  beC2USe  iC 

functioning  of  your  own       ^         °f  memory  ^nd  the 

rely  on  the^o  *  ZaZgT  ^^  **tead'  y°U  should 


Chapter  6:  Memory,  Segments,  and  Files 


For  a  complete  description  of 
Memory  Manager  functions,  see 
"Memory  Manager"  in  the  Apple 
IIGS  Toolbox  Reference. 


What  the  Memory  Manager  does 

The  Memory  Manager  is  a  ROM-resident  Apple  IIGS  tool  set  that 
controls  the  allocation,  deallocation,  and  repositioning  of 
memory  blocks  in  the  Apple  IIGS.  The  Memory  Manager  works 
closely  with  ProDOS  16  and  the  System  Loader  to  provide  the 
needed  memory  spaces  for  loading  programs  and  data  and  for 
providing  I/O  buffers.  All  Apple  IIGS  software,  including  the 
System  Loader  and  ProDOS  16,  must  obtain  needed  memory- 
space  by  making  calls  to  the  Memory  Manager. 

The  Memory  Manager  keeps  track  of  how  much  memory  is  free 
and  what  parts  are  allocated  to  whom.  Memory  is  allocated  in 
blocks  of  arbitrary  length;  each  block  possesses  several  attributes 
that  describe  how  the  Memory  Manager  may  modify  it  (such  as 
moving  it  or  deleting  it),  and  how  it  must  be  aligned  in  memory 
(for  example,  on  a  page  boundary).  Table  6-1  describes  the 
memory  block  attributes  and  lists  the  predefined  constants  with 
which  each  can  be  specified. 


Table  6-1 

Memory  block  attributes 


Attribute 


Fixed  (yes/no) 


Constant' 


Explanation 


attrFixed 


Fixed  address  (yes/no)  attrAddr 

Fixed  bank  (yes/no)  attrBank 

Bank-boundary  limited  (yes/no)  attrNoCross 

Special  memory  not  usable  (yes/no)  attrNoSpec 


attrPage 
attrPurge 

attrLocked 


Page-aligned  (yes/no) 
Purge  level  (0  to  3) 

Locked  (yes/no) 

*  Equivalent  to  "yes"  if  present 


Must  the  block  remain  at  the  same  location 
in  memory? 

Must  it  be  at  a  specific  address? 

Must  it  be  in  a  particular  memory  bank? 

Is  it  prohibited  from  extending  across  a 
bank  boundary? 

Is  it  prohibited  from  residing  in  banks  $00, 
$01,  and  parts  of  banks  $E0,  $E1? 

Must  it  be  aligned  to  a  page  boundary? 

Can  it  be  purged  (made  available  for  other 
use)?  If  so,  with  what  priority? 

Is  the  block  locked  (temporarily  fixed  and 
unpurgeable)? 
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The  System  Loader  is  described 
under  "Loading  Programs  and 
Segments."  later  in  this  chapter. 


♦  HodgePodge:  For  an  example  of  the  use  of  predefined 

constants  (column  2  of  Table  6-1)  in  specifying  memory-block 
attributes,  see  any  of  HodgePodge 's  NewHandle  calls— such  as 
in  the  routine  StartUpTools  (Chapter  2).  See  also  "How  Your 
Application  Obtains  Memory,"  later  in  this  section. 

Memory-block  attributes  are  specified  in  an  attributes  word. 

When  you  request  a  block  of  memory,  you  supply  the  attributes 
word  for  that  block.  Later,  you  can  modify  the  value  of  the 
attributes  word  to  change  the  block's  characteristics. 

In  addition  to  creating  and  deleting  memory  blocks,  the  Memory 
Manager  moves  blocks  when  necessary  to  consolidate  free 
memory  and  relieve  memory  fragmentation.  When  it  compacts 
memory  in  this  way  (Figure  6-1),  the  Memory  Manager  can  move 
only  those  blocks  that  needn't  be  fixed  in  location.  Therefore  as 
many  memory  blocks  as  possible  should  be  movable  (not  fixed), 
if  the  Memory  Manager  is  to  be  efficient  in  compaction.  Data 
segments  and  segments  containing  position-independent  code 
can  generally  be  placed  in  movable  blocks. 


Before  compaction 


After  compaction 


Fixed  blocks     Movable  blocks    Free  memory 

Figure  6-1 

Memory  fragmentation  and  compaction 
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Pointers  and  handles  to  memory  blocks 

To  access  an  entry  point  in  a  movable  block,  an  application  can- 
not use  a  simple  pointer,  because  the  Memory  Manager  may  move 
the  block  and  change  the  entry  point's  address.  Instead,  each  time 
the  Memory  Manager  allocates  a  memory  block,  it  returns  to  the 
requesting  application  a  handle  referencing  that  block. 

A  handle  is  a  pointer  to  a  pointer:  it  is  the  address  of  a  fixed  (non- 
movable)  location  that  contains  the  address  of  the  block.  If  the 
Memory  Manager  changes  the  location  of  the  block,  it  updates  the 
address  in  the  fixed  location;  the  value  of  the  handle  itself  is  not 
changed.  Thus  the  application  may  continue  to  access  the  block  by 
using  the  handle,  no  matter  how  often  the  block  itself  is  moved  in 
memory. 


a.  Pointer: 

Value  of  pointer  = 

starting  address  of  memory  block 


$XXX 


$XXX 


Memory  block 


Memory  block 


b.  Handle: 

Value  of  handle  = 
address  of  master  pointer 


•$xxx 


$ZZZ 


"*$ZZZ 


Master  pointer 


$XXX 


Figure  6-2 

Pointer  and  handle 


If  a  block  will  always  be  in  the  same  place  in  memory  (that  is 
either  locked  or  fixed),  it  may  be  referenced  by  a  pointer  instead 
of  by  its  handle.  To  obtain  a  pointer  to  a  particular  block  or 
location,  an  application  can  dereference  the  block's  handle.  The 
application  reads  the  address  stored  in  the  location  pointed  to  by 
the  handle — that  address  is  the  pointer  to  the  block.  Of  course,  if 
the  block  is  ever  moved  that  pointer  is  no  longer  valid. 
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Deref 


START 

sta 

0 

stx 

2 

ldy 

#4 

Ida 

[0] 

,Y 

ora 

#$8000 

sta 

[0] 

-y 

dey 

dey 

Ida 

[0] 

Y 

tax 

lda[0] 

rts 

In  most  high-level  languages,  dereferencing  is  a  simple,  single- 
statement  task.  For  example,  in  C  the  statement 


z=*y 


dereferences  the  memory  handle    y.  The  variable    z    now  contains 
a  pointer  to  the  memory  block  whose  handle  is    y.  In  assembly- 
language  it  takes  a  few  more  statements;  the  HodgePodge  routine 
Deref  (in  the  file  GLOBALS  .  ASM)  looks  like  this: 


store   low  word  of   handle   at    zero-page   address   0 

store   high   word   of   handle    at    zero-page    address   2 

put   the   value    "4"    in   Y   register 

set    the... 

...attributes   bit   that... 

...locks   the   block 

now   Y=3 

now   Y=2 

put   high  word   of   pointer    into   acumulator 

put    high  word  of  pointer   in   X   register 

put    low  word   of   pointer    in   accumulator 

return   to   caller 


A  memory  handle  that  points  to  a 
value  of  zero  is  called  NIL. 


When  a  memory  block  is  purged,  the  memory  that  its  handle 
pointed  to  becomes  available  for  other  use  but  the  handle  itself 
remains  in  memory.  A  purged  memory  handle  points  to  the 
address  $00  0000,  but  retains  its  User  ID  and  all  its  attributes  as 
listed  in  Table  6-1,  so  that  the  memory  block  can  be  quickly  and 
easily  reallocated  if  necessary. 

When  all  the  attributes  of  a  memory  handle  as  well  as  the 
memory  it  points  to  are  discarded,  the  handle  is  said  to  be 
disposed.  A  disposed  memory  handle  is  no  longer  associated  with 
a  particular  program.  Your  application  can  get  rid  of  memory  it 
no  longer  needs  by  making  a  DisposeHandle  call. 

Pointers  and  handles  must  be  at  least  3  bytes  long  to  access  the 
full  range  of  Apple  IIGS  memory.  However,  pointers  and  handles 
passed  as  parameters  are  always  4  bytes  long,  because  they  are 
then  easier  to  manipulate  in  the  l6-bit  registers  of  the  65C816 
microprocessor. 


Important 


Do  not  use  the  high-order  byte  of  a  4-byte  pointer  or  handle  to 
store  data.  The  unused  byte  is  reserved  for  system  use-your 
application  should  always  fill  It  with  zeros 
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How  your  application  obtains  memory 

When  an  application  makes  a  call  to  the  operating  system  or 
other  system  software  that  requires  allocation  of  memory  (such  as 
opening  a  file  or  writing  from  a  file  to  a  memory  location),  the 
system  software  first  obtains  any  needed  memory  blocks  from  the 
Memory  Manager  and  then  performs  its  tasks.  When  an 
application  informs  the  operating  system  that  it  no  longer  needs 
that  memory,  the  information  is  passed  on  to  the  Memory 
Manager  which  in  turn  frees  that  application's  allocated  memory. 
In  these  cases  the  memory  allocation  and  deallocation  is 
completely  automatic,  as  far  as  the  application  is  concerned. 


Requesting  memory 

Any  other  memory  that  an  application  needs  for  its  own  purposes 
must  be  requested  directly  from  the  Memory  Manager.  The 
shaded  areas  in  Figure  6-3  represent  those  parts  of  the  Apple  IIGS 
memory  that  can  be  allocated  through  requests  to  the  Memory 
Manager.  Apple  IIGS  applications  should  avoid  requesting 
absolute  (fixed-address)  blocks — it  defeats  the  Memory  Manager's 
ability  to  allocate  memory  as  efficiently  as  possible,  and  increases 
the  probability  that  the  program  will  not  be  able  to  load  or  run. 


■Bank  numbers  - 


SFFFF— 

SE000- 

SDOOO- 

scooo- 


$00  $01    $02 


$7F 


$E0  $E1 


$0800- 


1 

1 

Figure  6-3 

Memory  allocatable  through  the  Memory  Manager 
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Your  application  requests  memory  with  the  Memory  Manager's 
NewHandle  call.  Here  is  an  example  from  HodgePodge: 


toolsZeroPage  := 


NewHandle (TotalDP, 

myMemorylD, 


Direct-page  space  is  descriPed 
in  more  detail  later  in  this  chapter. 


attrBank+attrFixed+attrLocked+attrPage, 

XT  L.  J.    \\J )   J   f 

In  this  example  HodgePodge  is  requesting  direct-page  space  for 
tool  set  use.  ToolsZeroPage  is  a  handle  to  the  requested  space 
Inputs  to  the  call  are:  size  (TotalDP),  User  ID  (myMemorylD) 
predefined  constants  specifying  attributes  (as  described  in  Table 

case)"      "  P°inter  t0  WhGre  thC  bl°Ck  iS  t0  ^^  Cbank  $0°  in  this 


The  User  ID  Manager  is  descriPed 
under  "Miscellaneous  Tool  Set" 
in  the  Apple  IIgs  Toolbox 
Reference. 


User  IDs 

Many  Memory  Manager  calls  use  the  block's  User  ID  a  code 
number  that  shows  what  program  owns  the  memory  block  User 
ID  s  are  assigned  by  the  User  ID  Manager. 

When  your  application  starts  up  the  Memory  Manager  the 
operating  system  has  already  assigned  a  master  User  lb  for  that 
mT^iT  °fTlne  aPPlication-  The  grating  system  gives  the 

pTsses  thSm  i nUmb6r  t0  ,thG  MCm0ry  Manager'  which  in  ^ 
passes  that  ID  to  your  application  in  the  MMStartUp  call  You 

must  save  that  ID  for  use  when  you  shut  down  your  application. 


Bit: 
Value: 


Bytel 

ByteO 

15 

14 

13 

12 

11  1  10 

9    |   8 

7 

6 

5 

4      3      2 

i  Inl 

typelD 

auxlD 

mainID 

1 

1 

Figure  6-4 

User  ID  format 

2"  6"T4nsho^S'  User  IDs  «  ™de  "P  of  three  fields-the 
typelD,  auxip,  and  mainID  fields-contained  in  a  word-length 

SSS^t^r  m  ^^  fidd  iS  assigned  by  ^«m 
eenerSkilH  o^P  ^  ^^  *  number  that  describe«  the 

as  anon ir     °fHpr°gram  se*ment  tha'  will  occupy  the  block-such 
as  application,  desk  accessory,  or  tool  set.  The  auxlD  field  is 

vX;  s  otur  *  T  ^  Pr°8ram  reqUeSting  the  ™»5 'its  in* 
value  is  0;  your  application  can  store  any  4-bit  value  there 
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Using  the  auxID  field,  your  application  can  create  up  to  15  new 
and  distinct  User  IDs  from  the  single  master  User  ID  returned  by 
the  Memory  Manager  at  startup.  You  can  use  each  new  User  ID  to 
allocate  as  many  additional,  private  memory  blocks  as  needed; 
when  finished  with  the  memory  allocated  under  a  particular  ID, 
discard  it  all  at  once  by  calling  DisposeAll  with  that  ID.  An 
example  of  this  technique  is  shown  in  the  following  assembly- 
language  code  fragment. 

pushword  #0  ;  space  for  master  User  ID 

_MMStartUp 

pla  ;  retrieve  master  User  ID 

sta  MasterlD  ;  store  master  User  ID 

ora  #$0100  ;  create  User  ID  with  AUX  ID  =  1 

sta  MylD  ;  store  ID  for  use  w/  private  memory 

...  ;  (your  code  here) 

...  ;  (ready  to  exit  program) 

pushword  MylD 

_DisposeAll  ;  discard  all  of  my  private  memory 

...  ;  (continue  with  termination 

...  ;  processing) 

Important      Do  not  specify  an  auxID  of  0.  The  Memory  Manager  routines 

PurgeAII  and  DisposeAll  treat  an  auxID  field  with  0  in  it  as  a  wildcard 
that  matches  all  values. 

The  main  advantage  of  this  method  is  that  you  can  dispose  of  all 
allocated  blocks  quickly  and  easily,  with  a  DisposeAll  call,  instead 
of  making  sure  to  keep  track  of  all  allocated  blocks  and 
deallocating  them  individually. 

You  don't  have  to  use  this  method.  You  could  simply  use  the 
master  User  ID,  unchanged,  to  obtain  new  private  memory. 
However,  your  application  could  not  then  use  the  DisposeAll  call 
to  discard  everything — it  would  be  disposing  of  itself  too.  Another 
method  is  to  obtain  an  entirely  new  User  ID  for  private  memory. 
This  method  allows  you  to  discard  all  private  memory  at  once, 
but  leaves  open  the  possibility  of  allocated  blocks  remaining  in 
memory  after  your  application  quits. 

♦  HodgePodge:  HodgePodge  makes  very  few  memory-allocation 
requests.  It  uses  an  unmodified  master  User  ID  when  it  does  so, 
and  it  makes  sure  to  dispose  of  its  requested  memory  blocks 
individually. 
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Important 


For  more  Information  on  memory 
management,  see  the  Apple  IIgs 
Toolbox  /?eferenceandthe 
Apple  IIGS  ProDOS  16  Reference. 

important 


Locking  and  unlocking,  purging  and  disposing 

If  you  need  to  access  a  movable  memory  block  directly— that  is 
you  need  to  dereference  its  handle-you  must  first  lock  it  so  that 
it  won  t  move  while  you  are  using  it.  When  you  no  longer  need  it 
to  be  locked,  make  sure  to  unlock  it  so  the  Memory  Manager  can 
move  it  during  compaction.  Don't  lock  blocks  that  you  are  not 
currently  accessing. 

If  you  are  temporarily  through  using  a  block,  and  don't  mind  if  its 
contents  must  be  reconstructed  the  next  time  they  are  needed 
you  can  set  the  block's  purge  level  to  make  it  purgeable.  Then 'the 
Memory  Manager  can  purge  it  if  more  space  is  needed  If  the 
Memory  Manager  does  purge  a  block,  you  can  quickly  restore  it 
with  the  same  attributes,  User  ID,  and  size. 


1 


When  the  Memory  Manager  purges  a  block,  all  data  in  it  is  lost.  Your 
a     [o  ria  "    reSp°nsible  for  savina  and  rest°^g  the  data 


J 


When  your  application  is  completely  finished  with  its  own  private 
memory  ,t  should  dispose  of  it-for  example,  by  calling  the 
DisposeAl  routine  and  specifying  the  User  ID  with  a  modified 
auxID  field,  as  described  earlier.  If  your  application  doesn't 
dispose  of  all  memory  that  it  has  acquired,  the  memory 
management  system  can  become  clogged 


Do  not  call  DisposeAII  with  the  unmodified  master  User  ID  fervour 
own  program  (the  one  In  which  auxID  =  0).  Y 


The  System  Loader  Is  described 
In  the  next  section  of  this  chapter. 


Load  segments  and  memory  blocks 

In  Chapter  1  we  introduced  the  idea  of  segmented  programs  The 
execu tabe  versions  of  program  files  are  called  load  files,  and  h  v 
consist  of  one  or  more  load  segments.  Load  segments  are  1 

placed  in  memory  by  the  System  Loader.  The  System  Loader  mu  J 
work  closely  with  the  Memory  Manager  because'dfffLnUy™1 
segments  require  memory  blocks  with  different  attributes. 
When  the  System  Loader  loads  a  program  segment,  it  calls  the 
Memory  Manager  to  allocate  a  memory  block  for  the  segmen 

the  at  Hn  I1'8  TT^  *  ^  """^  b,°Ck  ™  <*«***  I 
the  attributes  of  the  segment  that  will  inhabit  the  block. 
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If  the  program  segment  is  static,  and  therefore  must  not  be 
unloaded  or  moved,  its  memory  block  is  marked  as  unpurgeable 
and  fixed.  That  means  that  the  Memory  Manager  cannot  change 
that  segment's  position  or  contents  as  long  as  the  program  is 
running.  If  the  program  segment  is  dynamic,  its  memory  handle  is 
initially  marked  as  purgeable  but  locked  (temporarily  unpurgeable 
and  fixed;  subject  to  change  at  the  request  of  the  application).  If 
the  dynamic  segment  is  position-independent,  its  memory  handle 
is  marked  as  movable;  otherwise,  it  is  fixed. 

In  summary,  a  typical  load  segment  will  be  placed  in  a  memory 
block  that  is 

□  locked 

□  fixed 

D  purge  level  =  0  (that  is,  unpurgeable)  if  the  segment  is  static 
D  purge  level  =  1  if  the  segment  is  dynamic 

Depending  on  other  requirements  the  segment  may  have,  such  as 
alignment  in  memory,  the  load  segment-memory  block 
relationship  may  be  more  complex.  Consult  the  Apple  IIGS 
ProDOS  16  Reference  for  details. 


Loading  programs  and  segments 

The  System  Loader  loads  all  programs  and  segments  of  programs. 
It  is  called  by  ProDOS  16  when  an  application  starts  or  quits,  it  is 
called  automatically  to  load  dynamic  segments  during  program 
execution,  and  it  can  be  called  by  your  application  to  load  and 
unload  other  programs  or  program  segments.  This  section 
describes  both  the  automatic  operation  of  the  loader  and  the 
ways  in  which  your  program  can  call  it  directly. 

♦  Note:  If  you  are  writing  a  typical  application,  you  don't  have  to 
call  the  System  Loader  at  all.  All  its  operations  are  automatic 
for  most  programs,  even  those  with  dynamic  segments.  If  you 
are  not  interested  in  System  Loader  details,  skip  ahead  to 
"Quitting  and  Launching  Under  ProDOS  16." 

♦  HodgePodge:  HodgePodge  makes  no  loader  calls. 
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The  System  Loader,  although  a 
tool  set,  is  documented  In  the 
Apple  IIGS  ProDOS  16  Reference 


The  Jump  Table,  Pathname 
Table,  and  other  System  Loader 
tables  are  discussed  In  detail  in 
the  Apple  IIGS  ProDOS  16 
Reference 


How  the  System  Loader  works 

The  System  Loader  is  the  Apple  IIGS  tool  set  that  manages  the 
loading  of  program  segments  into  the  Apple  IIGS.  It  works  very 
closely  with  the  Memory  Manager  and  with  the  ProDOS  16 
operating  system. 

The  System  Loader  is  a  program  that  processes  load  files — it  is 
not  concerned  with  source  files  or  object  files.  Each  load  file 
consists  of  load  segments  that  the  loader  treats  differently, 
depending  upon  their  attributes: 

■  Static  segments  are  loaded  into  memory  at  application  startup. 
They  stay  in  memory  until  the  program  quits. 

■  Dynamic  segments  are  placed  in  memory  only  as  needed 
during  program  execution.  They  may  be  removed  when  no 
longer  needed. 

■  Absolute  segments  are  loaded  at  specified,  fixed  locations  in 
memory. 

■  Relocatable  segments  are  placed  wherever  the  System  Loader 
can  find  sufficient  memory  space.  Once  they  are  loaded,  their 
memory  blocks  are  locked  so  they  can't  move. 

■  Position-independent  segments  are  placed  wherever  the  System 
Loader  can  find  sufficient  memory  space.  Their  memory  blocks 
are  initially  locked,  but  once  unlocked  they  can  be  moved  from 
one  location  to  another  between  executions. 

Some  load  segments  consist  of  typical  program  code  or  data; 
others  are  more  specialized.  The  Jump  Table  segment,  when 
loaded  into  memory,  becomes  the  Jump  Tablej  it  provides  a 
mechanism  by  which  segments  in  memory  can  trigger  the  loading 
of  other  needed  segments.  The  Pathname  segment  becomes  the 
Pathname  Table,  a  cross-reference  between  pathnames  on  disk 
and  load  segments  in  memory.  An  initialization  segment 
contains  any  code  that  has  to  be  executed  first,  before  the  rest  of 
the  segments  are  loaded. 

When  the  System  Loader  is  called  to  load  a  program,  it  loads  all 
static  load  segments  and  constructs  the  tables  necessary  to  allow 
automatic  loading  of  dynamic  segments. 
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Controlling  programsare 
dscussed  under  "Loading 
Applications,"  later  In  this  section. 


To  unload  a  segment,  the  System  Loader  calls  the  Memory 
Manager  to  make  the  corresponding  memory  block  purgeable.  If 
the  segment  is  dynamic,  the  loader  also  alters  the  Jump  Table  to 
reflect  the  fact  that  the  segment  may  no  longer  be  in  memory. 

To  unload  all  segments  associated  with  a  particular  application 
(for  example,  at  shutdown),  a  controlling  program  such  as  a  shell 
calls  the  System  Loader's  User  Shutdown  function,  which  in  turn 
calls  the  Memory  Manager  to  make  purgeable,  purge,  or 
dispose  of  the  application's  memory  blocks  (depending  whether 
the  application  is  restartable  or  not — see  "Shutting  Down  and 
Restarting  Programs  in  Memory,"  later  in  this  section). 


Loading  a  relocatable  segment 

When  a  relocatable  segment  is  loaded  into  memory,  its  code  is 
placed  at  the  location  assigned  to  it  by  the  Memory  Manager.  The 
loader  then  performs  relocation  on  the  code — it  patches  address 
operands  that  refer  to  locations  both  within  and  external  to  the 
segment. 

1.  Local  references  are  coded  in  the  load  segment  as  offsets  from 
the  beginning  of  the  segment.  The  loader  adds  the  starting 
address  of  the  segment  to  each  offset,  so  that  the  correct 
memory  address  is  referenced. 

2.  External  references  may  be  to  routines  in  static  or  dynamic 
segments.  If  the  reference  is  to  a  static  segment,  the  loader 
finds  the  memory  location  of  the  routine  in  that  static  segment 
and  patches  the  reference  with  its  address.  If  the  reference  is  to 
a  dynamic  segment,  the  loader  patches  the  reference  to  point 
to  a  Jump  Table  entry.  The  Jump  Table  entry  contains  the 
information  necessary  to  transfer  control  to  the  external 
segment  when  it  is  loaded. 

You  can  see  that  most  Apple  IIGS  code  cannot  be  moved  once  it 
is  in  memory:  relocation  happens  only  when  the  segment  is 
loaded,  so  if  the  segment  is  ever  moved  its  address  operands  will 
no  longer  be  correct.  Only  position-independent  code,  which 
needs  no  relocation,  can  be  moved  around  in  memory.  And 
position-independent  code  is  difficult  to  write — therefore,  most 
Apple  IIGS  code  is  relocatable,  but  not  position-independent. 
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Object  module  format  is  the  file 
format  produced  by  Apple  llss 
development  systems  such  as 
the  Apple  llss  Programmer's 
Workshop.  See  Chapter  7. 


Loading  applications 

The  functioning  of  the  System  Loader  is  completely  transparent 
to  most  applications.  Any  program  that  is  in  proper  object 
module  format  (with  any  combination  of  static  and  dynamic 
segments)  will  be  automatically  loaded,  relocated,  and  executed 
whenever  it  is  called.  Unless  you  want  your  program  to  load 
dynamic  segments  manually,  or  load  and  execute  other  progams, 
you  need  not  know  how  to  use  the  System  Loader. 

However,  you  can  indirectly  affect  the  functioning  of  the  System 
Loader  by  the  method  in  which  you  segment  your  programs.  If 
your  program  is  divided  into  static  and  dynamic  segments,  you 
may  experiment  with  several  configurations  of  a  single  program 
after  it  has  been  assembled  to  see  how  loading  of  dynamic 
segments  affects  performance.  See  Chapter  7  for  further  program 
design  considerations  involving  static  and  dynamic  segments. 


Application  control  of  segment  loading 

Most  applications  do  not  need  to  make  loader  calls  directly,  but 
for  programs  with  specialized  requirements  the  System  Loader 
offers  this  capability. 


One  advantage  of  manually  loading  a  dynamic  segment  is  that  the 
segment  can  be  referenced  in  a  more  direct  manner  than  an    j 
automatically  loaded  dynamic  segment.  Automatically  loaded 
dynamic  segments  can  be  referenced  only  through  a  JSL  to  the  j 
Jump  Table;  however,  if  the  segment  consists  of  data  such  as  a 
table  of  values,  you  would  want  to  simply  access  those  values 
rather  than  passing  execution  to  the  segment.  By  manually 
loading  the  segment  into  a  locked  memory  block,  and 
dereferencing  its  memory  handle  (obtaining  a  pointer  to  the  start 
of  the  segment),  you  can  then  reference  any  location  in  the  table 
directly.  Of  course,  because  the  loader  does  not  resolve  any 
symbolic  references  in  the  manually  loaded  segment,  the 
application  must  know  the  segment's  exact  structure. 

Your  program  is  responsible  for  managing  the  segments  it  loads. 
That  is,  it  must  unload  them  with  System  Loader  calls  when  they 
are  no  longer  needed. 
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The  ProDOS  16  QUIT  call  is 

explained  under  "Quitting  and 
Launching  Under  ProDOS  16,"  later 
In  this  chapter. 


More  detailed  requirements  for 
controlling  programs  and  their 
subprograms  (called  shell 
applications)  are  listed  in 
Chapter  8. 


Loading  by  controlling  programs  (shells) 

A  program  may  cause  the  loading  of  another  program  in  one  of 
two  ways: 

□  The  program  can  make  a  ProDOS  16  QUIT  call.  ProDOS  16 
and  the  System  Loader  remove  the  quitting  program  from 
memory,  then  load  and  execute  the  specified  new  program. 

□  The  program  can  call  the  System  Loader  directly.  The  loader 
loads  the  specified  new  program  without  unloading  the  original 
program,  then  hands  control  back  to  the  original  program. 

Most  applications  use  the  first  method.  Even  if  you  want  your 
application  to  launch  another  specific  program,  and  even  if  you 
want  control  to  return  to  your  application  after  the  succeeding 
program  quits,  the  ProDOS  16  QUIT  call  is  all  that  is  needed.  For 
example,  a  finder  or  program  launcher,  which  always  regains 
control  between  execution  of  applications,  uses  the  QUIT  call  to 
launch  the  applications. 

Programs  that  use  the  second  method  are  called  controlling 
programs.  Certain  types  of  finders,  switchers,  and  shells  may  be 
controlling  programs.  ProDOS  16  is  a  controlling  program;  the 
Apple  IIGS  Programmer's  Workshop  Shell  is  a  controlling 
program.  An  application  needs  to  be  a  controlling  program  only 
if  it  must  remain  in  memory  after  it  calls  another  program,  usually 
because  it  has  functions  or  sets  up  an  environment  needed  by  the 
programs  it  executes. 

The  controlling  program  is  completely  responsible  for  the 
subprogram's  ultimate  disposition.  When  the  subprogram  is 
finished,  the  controlling  program  must  remove  it  from  memory 
and  release  all  resources  associated  with  its  User  ID.  The  best  way 
to  do  this  is  to  call  the  System  Loader's  User  Shutdown  function. 


Shutting  down  and  restarting  programs  in  memory 

By  using  System  Loader  calls,  a  controlling  program  can  rapidly 
switch  execution  among  several  applications.  For  switching  to  be 
efficient,  the  loader  must  be  able  to  shut  a  program  down  without 
removing  it  from  memory,  and  the  program  must  be  able  to  re- 
execute  itself  without  having  to  be  reloaded  from  disk. 
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Restartable  software  reinitializes 
its  variables  every  time  it  gains 
control;  It  also  makes  no 
assumptions  about  the  state  of 
the  machine  it  will  find  when  It 
starts  up. 


The  User  Shutdown  function  can  put  an  application  into  such  a  L 
dormant  state.  It  does  this  by  purging  an  application's  dynamic 
segments,  and  making  all  its  static  segments  purgeable.  This 
process  frees  space  but  keeps  the  dormant  application's  essential 
segments  in  memory.  As  long  as  all  the  static  segments  are  still  in 
memory,  the  Restart  function  brings  the  application  back  rapidly 
because  disk  access  is  not  necessary.  However,  if  for  any  reason 
the  Memory  Manager  purges  one  of  those  static  segments,  the  1 
application  can  no  longer  be  restarted — the  next  time  it  is 
needed,  it  must  be  loaded  from  its  disk  file. 

Only  software  that  is  restartable  can  be  executed  in  this  way.  In 
general,  if  your  program  has  a  code  routine  that  defines  and 
initializes  all  variables,  and  if  that  routine  is  called  every  time  the 
program  runs,  and  if  the  code  in  that  routine  is  not  modified 
during  execution,  the  program  is  probably  restartable. 

When  an  application  quits  with  a  ProDOS  16  QUIT  call  (described 
next),  it  tells  its  controlling  program  whether  it  (the  application) 
is  restartable  or  not.  (The  controlling  program  simply  takes  the  I 
application's  word  for  this,  by  the  way.)  If  the  application  says  it 
wants  to  be  restarted  and  claims  to  be  restartable,  the  controlling 
program  makes  it  dormant.  If  the  application  says  it  is  not 
restartable,  the  controlling  program  removes  all  of  its  segments 
from  memory. 

♦  Note:  It  is  difficult  to  make  some  programs  in  some  languages 
restartable;  they  require  initialization  information  to  be  loaded 
from  disk  every  time  they  execute.  To  help  in  such  cases,  the 
System  Loader  supports  RELOAD  segments.  If  all  initializatioJl 
information  is  put  into  a  RELOAD  segment,  a  program  that  1 
could  not  otherwise  be  restarted  can  make  itself  restartable. 
When  a  program  is  restarted  from  a  dormant  state,  only  its 
RELOAD  segments  (plus  any  initialization  segments)  are  read 
from  disk. 


Quitting  and  launching  under  ProDOS  16 

ProDOS  16  and  the  System  Loader  provide  a  sophisticated 
method  for  passing  control  among  different  applications. 
Through  the  ProDOS  16  QUIT  call,  an  application  can  do  one  o. 
three  things: 

□  Quit  permanently. 
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□  Quit  permanently,  but  tell  ProDOS  16  to  launch  another 
specified  application. 

□  Quit  to  a  specified  application  temporarily,  telling  ProDOS  16 
it  wants  to  be  re-executed  after  the  specified  application  quits. 

When  it  launches  another  application  or  quits  temporarily 
through  the  QUIT  call,  an  application  is  not  functioning  as  a 
controlling  program.  It  is  not  maintained  in  memory  (except, 
possibly,  in  a  dormant  state)  while  the  other  program  executes.  A 
finder  or  program  launcher,  for  example,  is  an  application  that 
quits  temporarily  each  time  an  application  is  launched,  returning 
after  the  application  quits.  It  is  not  a  shell. 

♦  Note:  If  you  are  writing  a  typical  application  in  a  high-level  lan- 
guage, you  may  not  need  any  of  the  information  here — your 
compiler  determines  the  manner  in  which  your  program  quits. 
If  you  are  writing  a  typical  application  in  asssembly  language,  be 
sure  to  read  the  "HodgePodge"  note  at  the  end  of  this  section. 


The  system  file  level  is  described 
later  In  this  chapter,  under  "The 
ProDOS  File  System." 


Quitting,  launching,  and  returning 

Calling  QUIT  terminates  the  present  application.  It  also  closes  all 
open  files,  sets  the  current  system  file  level  to  zero,  and 
deallocates  any  installed  interrupt  handlers.  ProDOS  16  can  then 

□  launch  a  file  specified  by  the  quitting  program 
a  automatically  launch  a  program  specified  in  the  quit  return 
stack 

The  quit  return  stack  is  a  table  of  User  ID's  maintained  in  memory 
by  ProDOS  16.  It  provides  a  convenient  means  for  a  program  to 
function  like  a  shell — the  program  can  pass  execution  to 
subsidiary  programs  (even  other  shell-like  applications),  while 
ensuring  that  control  eventually  returns  to  it. 

For  example,  a  program  selector  may  push  its  User  ID  onto  the 
quit  return  stack  whenever  it  launches  an  application  (by  making  a 
QUIT  call).  That  program  may  or  may  not  specify  yet  another 
program  when  it  quits,  and  it  may  or  may  not  push  its  own  User 
ID  onto  the  quit  return  stack.  Eventually,  however,  when  no  more 
programs  have  been  specified  and  no  others  are  waiting  for 
control  to  return  to  them,  the  program  selector's  User  ID  will  be 
pulled  from  the  stack  and  it  will  be  executed  once  again. 

When  your  application  makes  a  QUIT  call,  it  specifies  these  two 
parameters: 
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The  exact  format  of  the  flag  word, 
and  the  rest  of  the  ProDOS  16  QUIT 
call,  is  given  in  the  Apple  IIGS 
ProDOS  16  Reference. 


Using  the  ProDOS  8  QUIT  call  on  the 
Apple  IIGS  is  discussed  in  the 
Apple  IIGS  ProDOS  16  Reference, 


1.  Pathname  pointer — if  specified,  it  indicates  the  program  to  be 
loaded  and  executed.  If  no  pathname  is  specified,  ProDOS  16 
pulls  a  User  ID  from  the  quit  return  stack  and  executes  the 
program  with  that  User  ID. 

2.  Flag  word — it  contains  two  boolean  values:  a  return  flag  and  a 
restart-from-memory  flag.  The  return  flag  tells  ProDOS  16 
whether  the  program  making  the  QUIT  call  wants  to  return;  if 
so,  its  User  ID  is  pushed  onto  the  quit  return  stack.  The  restart- 
from-memory  flag  tells  ProDOS  16  whether  the  quitting 
program  is  restartable.  If  it  is  not,  the  program  must  be 
reloaded  from  disk  the  next  time  it  is  run.  The  information 
from  this  flag  is  saved  on  the  quit  return  stack  along  with  the 
User  ID. 

♦  ProDOS  8:  This  automatic  return  mechanism  is  specific  to  the 
ProDOS  16  QUIT  call,  and  therefore  is  not  available  to  ProDOS  I 
8  programs  on  the  Apple  IIGS.  When  a  ProDOS  8  application 
quits,  it  can  pass  control  to  another  program  but  it  cannot  put 
its  own  ID  on  the  quit  return  stack. 

How  a  particular  application  quits  is  language-specific.  For 
example,  C  programs  terminate  with  a  left-facing  bracket,  and 
Pascal  programs  end  with  an  END  .  statement.  In  either  case  there 
is  no  way  to  make  an  explicit  QUIT  statement.  The  actual  quit 
statement  is  inserted  when  the  program  is  compiled.  Assembly- 
language  programs,  however,  make  explicit  QUIT  calls. 

♦  HodgePodge:  The  assembly-language  version  of  HodgePodge 
has  the  followingProDOS  16  (macro)  QUIT  statement: 

_Quit        QuitParams 

where  the  _Quit  macro  translates  directly  into  a  ProDOS  16 
QUIT  call,  and  the  QuitParams  parameter  list  consists  of  four 
null  bytes  (corresponding  to  a  null  pathname  pointer), 
followed  by  a  word-length  flag  value  of  $4000  (meaning  that 
HodgePodge  is  restartable  from  memory). 


Setting  up  direct-page/stack  space 

For  assembly-language  programmers,  the  65C816  processor 
provides  the  convenience  of  a  direct  page.  Accessing  and 
indexing  from  direct-page  addresses  are  efficient  because  address 
operands  are  a  single  byte,  rather  than  the  three  bytes  required 
for  a  full  address  on  the  65C816. 
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For  all  programmers,  direct  page  is  of  interest  because  several 
Apple  IIGS  tool  sets  require  that  the  application  provide  direct- 
page  space  for  them. 

The  size  and  location  of  the  stack  may  also  be  of  particular 
interest  to  you  if  you  are  writing  heavily  recursive  routines  that 
require  large  stack  space. 


Standard-Apple  II  stack  and  zero 
page  are  discussed  In  the  Apple 
t  Technical  Reference  Manual 
and  the  Apple  lie  Technical 
Reference  Manual 


How  direct  page  and  stack  are  organized 

In  the  Apple  IIGS,  the  65C816  microprocessor's  stack  pointer 
register  is  16  bits  wide;  that  means  that  the  hardware  stack  may  be 
located  anywhere  in  bank  $00  of  memory.  Also,  the  stack  may  be 
as  much  as  64K  deep.  In  theory,  then,  the  stack  may  occupy  any 
unused  space  of  any  size  in  bank  $00. 

The  direct  page  is  the  Apple  IIGS  equivalent  to  the  zero  page  on 
a  standard  Apple  II  computer.  The  difference  is  that  it  need  not 
be  page  zero  in  memory.  Like  the  stack,  the  direct  page  may  be 
placed  in  any  unused  area  of  bank  $00.  The  microprocessor's 
direct  register  (D  register)  is  16  bits  wide,  and  all  zero-page 
(direct-page)  addresses  are  added  as  offsets  to  the  contents  of 
that  register.  Because  the  direct  page  can  be  located  anywhere  in 
bank  $00,  you  can  allocate  more  than  256  bytes  (that  is,  more 
than  one  page)  as  direct-page  space  for  your  program.  Then,  by 
changing  the  value  of  the  D  register  while  the  program  is  running, 
you  can  use  direct  addressing  to  access  any  portion  of  the  direct 
page  space. 

In  principle,  the  entire  64K  of  bank  $00  could  be  used  for  the 
combined  direct-page/stack  space.  In  practice,  however,  less  space 
is  available.  First,  only  the  lower  48K  of  bank  $00  can  be  allocated; 
the  rest  is  reserved  for  I/O  and  system  software.  Also,  because 
more  than  one  program  can  be  in  memory  at  a  time,  there  may 
be  more  than  one  stack  and  more  than  one  direct  page  in  bank 
$00.  Furthermore,  many  applications  may  have  parts  of  their  code 
as  well  as  their  stacks  and  direct  pages  in  bank  $00. 
Your  program  should  therefore  be  as  efficient  as  possible  in  its 
use  of  direct-page/stack  space.  The  total  size  of  both  should 
probably  not  exceed  about  4K  in  most  cases.  Still,  with  a  space 
that  size  you  can  write  programs  that  require  stacks  and  direct- 
page  space  much  larger  than  the  512  bytes  available  on  standard 
Apple  II  computers. 


Setting  up  direct-page/stack  space 
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♦  Note:  By  convention,  the  direct  page  and  stack  occupy  a  single 
memory  block  in  bank  $00.  Direct-page  addresses  are  positive 
offsets  from  the  base  of  the  allocated  space,  and  the  stack 
downward  from  the  top  of  the  space. 


Creating  a  direct-page/stack  segment 

Only  you  can  determine  how  much  stack  and  direct-page  space 
your  program  will  need  when  it  is  running.  The  best  time  to  make 
that  determination  is  during  program  development,  when  you  1 
create  your  source  files.  There  are  three  ways  to  allocate  the 
direct-page/stack  space  you  need: 

□  Define  it  as  a  program  segment. 

□  Use  the  ProDOS  16  default. 

□  Create  it  at  run  time. 


Define  it  as  a  program  segment 

You  can  specify  the  size  and  contents  of  your  program's  stack  and 
direct-page  space  by  creating  a  direct-page/stack  segment  when 
you  assemble  (or  compile)  and  link  your  program.  The  size  of  the 
segment  is  the  total  amount  of  stack  and  direct-page  space 
allocated  to  your  program,  and  the  contents  of  the  segment  are 
whatever  initial  contents  you  want  the  direct-page/stack  space 
to  have. 

Each  time  a  program  is  started,  the  System  Loader  looks  for  a 
direct-page/stack  segment.  If  it  finds  one,  it  loads  the  segment  and 
passes  its  base  address  and  size  to  ProDOS  16,  along  with  the 
program's  User  ID  and  starting  address.  ProDOS  16  sets  the  A 
(accumulator),  D  (direct),  and  S  (stack)  registers  as  shown  below, 
then  passes  control  to  the  program. 


Register 

Contents 

A 

User  ID  assigned  to  the  program 

D 

address  of  the  first  (lowest)  byte  in  the  direct- 
page/stack  space 

S 

address  of  the  last  (highest)  byte  in  the  direct- 
page/stack  space 
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LinkEd  Is  described  in  the  Apple 
HGS  Programmer's  Workshop 
Reference  An  example  of  a 
UnkEd  file  is  shown  in  •Creating 
Segmented  Code:  Three 
Examples"  in  Chapter  7. 


KIND  is  a  segment-description 
field.  See  "Object  Module 
Format"  in  the  Apple  HGS 
Programmer's  Workshop 
Reference  or  "System  Loader 
Technical  Data"  in  the  Apple  HGS 
ProDOS  16  Reference. 

1. 

Create  an 

object  segment 

of  proper  size. 

Object  file: 


Segment  1 


Segment  2 


Segment  m 


To  specify  the  direct-page/stack  space  for  your  program  use  the 
following  procedure  (in  APW  assembly  language,  using  LinkEd). 
See  also  Figure  6-5. 

1    Create  a  data  segment  in  your  source  file  with  the  size  and 
contents  you  want  for  your  initial  direct  page  and  stack. 

2.  Assemble  the  program. 

3.  Use  a  LinkEd  file  to  link  the  program.  Make  the  direct- 
page/stack  segment  a  load  segment  by  itself,  with  KIND=$0812 
(meaning  it  is  a  static,  absolute-bank,  direct-page/stack 
segment). 


Place  it  in  a  single 

direct-page/stack 

load  segment. 

Load  file: 


Segment  1 


The  System 

Loader 

loads  it 

into 

Bank 

S00. 


ProDOS  16  sets  the 
stack  register  to 

the  highest  address 
in  the  segment. 


Linker 


Segment  n 


Loader 


Direct  page 
and  stack 


ProDOS  16  sets  the 
direct  register 
to  the  lowest 

address  in 
the  segment. 


Figure  6-5 

Loading  a  direct-page/stack  segment 


Setting  up  direct-page/stack  space 
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See  the/Appte  IIGS  Toolbox 
Referenced  a  general 
description  of  memory  block 
attributes  assigned  by  the 
Memory  Manager. 


HodgePodge's  direct-page 
allocation  for  tool  sets  Is 
demonstrated  under  "Start  the 
Program"  In  Chapter  2. 


Use  the  ProDOS  16  default 

If  the  loader  finds  no  direct-page/stack  segment  in  a  file  at  load 
time,  ProDOS  16  itself  calls  the  Memory  Manager  to  allocate  a 
default  direct-page/stack  segment,  in  a  memory  block  with  these 
attributes: 


Size 
Owner 

Fixed/movable 

Locked/unlocked 

Purge  level 

May  cross  bank  boundary? 

May  use  special  memory? 

Alignment 

Absolute  starting  address? 

Fixed  bank? 


1,024  bytes 

program  with  the  User  ID 

returned  by  the  loader 

fixed 

locked 

1 

no 

yes 

page-aligned 

no 

yes — bank  $00 


Once  allocated,  the  default  direct-page/stack  space  is  treated  just 
as  it  would  be  if  it  had  been  specified  by  the  program:  ProDOS  16 
sets  the  A,  D,  and  S  registers  before  handing  control  to  the 
program,  and  at  shutdown  the  System  Loader  makes  the  segment 
purgeable. 

For  many  assembly-language  applications,  the  IK  default  stack 
and  direct  page  space  allocated  by  ProDOS  16  are  sufficient. 
Individual  high-level  language  systems  may  have  the  same  or 
different  default  sizes;  check  your  language  reference  manual. 

♦  HodgePodge:  HodgePodge  accepts  the  default  direct- 
page/stack  space  set  up  for  it  by  ProDOS  16.  In  addition,  it 
manually  creates  a  direct-page  space  for  tool  sets,  by  a  method 
similar  to  that  described  next,  under  "Create  It  at  Run  Time." 

Create  it  at  run  time 

If  the  ProDOS  16  default  space  is  the  wrong  size  for  your  applica- 
tion, and  if  for  some  reason  you  do  not  want  to  specify  the  size  of 
your  direct-page/stack  space  at  link  time,  you  can  include  ProDOS 
16  and  Memory  Manager  calls  in  your  program  that  allocate  a 
direct-page/stack  space  during  program  execution.  In  that  case, 
when  ProDOS  16  transfers  control  to  your  program,  save  the  User 
ID  value  left  in  the  accumulator  (or  use  the  User  ID  returned  by 
the  Memory  Manager  startup  call)  before  doing  the  following: 
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1.  Using  the  starting  or  ending  address  left  in  the  D  or  S  register 
by  ProDOS  16,  make  a  FindHandle  call  to  the  Memory 
Manager  to  get  the  memory  handle  of  the  automatically 
provided  direct-page/stack  space.  Then,  using  that  handle,  get 
rid  of  the  space  with  a  DisposeHandle  call. 

Z  You  can  now  allocate  your  own  direct-page/stack  space  through 
the  Memory  Manager  NewHandle  call.  Make  sure  that  the 
allocated  block  is  purgeable,  unmovable,  and  locked. 

3.  Place  the  appropriate  values  (beginning  and  ending  addresses 
of  the  segment)  in  the  D  and  S  registers. 

Cautions 

When  your  program  terminates  with  a  QUIT  call,  the  System 
Loader  makes  the  direct-page/stack  segment  purgeable,  along  with 
the  program's  other  static  segments.  Bank  $00  is  heavily  used,  and 
if  the  direct-page/stack  segment  is  purged,  your  entire  program 
will  have  to  be  reloaded  from  disk  when  it  reexecutes. 

If  your  direct-page/stack  load  segment  contains  initialization  data, 
you  need  to  make  it  a  RELOAD  segment  if  you  want  your  program 
to  be  restartable. 

There  is  no  provision  for  extending  or  moving  the  direct- 
page/stack  space  after  its  initial  allocation.  Because  bank  $00  is  so 
heavily  used,  the  space  you  request  may  be  unavailable — the 
memory  adjoining  your  stack  is  likely  to  be  occupied  by  a  locked 
memory  block.  Make  sure  that  the  amount  of  space  you  specify  at 
link  time  fills  all  your  program's  needs. 


Important     The  Apple  IIgs  provides  no  mechanism  for  detecting  stack 

underflow  or  overflow  (collision  of  the  stack  with  the  direct  page). 
Your  program  must  be  carefully  designed  and  tested  to  make  sure 
this  cannot  occur. 


The  term  ProDOS  (as  in  ProDOS  file 
system)  refers  to  features 
common  to  both  ProDOS  8  and 
ProDOS  16.  The  term  ProDOS  16  (as 
In  ProDOS  16 prefixes)  is  used  to 
describe  features  that  ProDOS  8 
does  not  have. 


The  ProDOS  file  system 

You  use  the  Apple  IIGS  disk  operating  system,  ProDOS  16,  to 
open,  close,  create,  delete,  and  otherwise  manipulate  files  on  disk. 
This  section  describes  the  filename  and  prefix  conventions  used 
by  ProDOS  16  and  introduces  some  of  the  ProDOS  16  functions 
that  your  program  may  call. 
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Filenames  and  pathnames 

and  it  must  begin  with  a  letter  Tow.  }'       d  penod 

Si 'Sr  *■  of  f — ,  each  preceded  tj 
volume  direao „    ,  '"  *  Pathnlm<i  '»  "he  name  of  a     ' 

leog.h  fo,  a  padmame  is  64  cha,a«etmtd^  s^h^,ra,", 


Pathname  prefixes 

name  alone,  or  it  mav  be  ,he  „„!  y  be  ^  vol™c 

more  names  of  suM ecodeS      eSos",  ,T ,  f^"  b7  °"e  °' 

padia,  P^oa,„eX?of .rad^r^;^"  ^  " 
""0|/,I6,7/Sv9CeX£  ^  ,0  *  '"•  "^  ""— 
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See  the  ProDOS  8  Technical 
Reference  Manualfot  more 
Information  on  ProDOS  8  prefix 
conventions. 


Table  6-2 

Examples  of  prefix  use 


*  /  Boot  prefix:  the  name  of  the  volume  from  which  the 

presently  running  ProDOS  16  was  booted. 

0/  Default  prefix:  (automatically  attached  to  any  partial 

pathname  that  has  no  prefix  number)— it  has  a  value 
dependent  on  how  the  current  program  was  launched.  In 
most  cases  the  default  prefix  is  equal  to  the  boot  prefix. 

1/  Application  prefix:  the  pathname  of  the  subdirectory 

that  contains  the  currendy  running  application. 

2/  System  library  prefix:  the  pathname  of  the  subdirectory 

(on  the  boot  volume)  that  contains  the  library  files  used 
by  applications. 
3/_7/     Null  strings:  (unless  previously  defined  by  an  application). 
Your  application  may  change  the  values  of  all  prefixes  except 
prefix  */. 

Prefix  0/   the  default  prefix,  is  similar  to  the  ProDOS  8  system 
prefix  in 'that  ProDOS  16  automatically  attaches  prefix  0/  to  any 
partial  pathname  for  which  you  specify  no  prefix.  However,  its 
initial  value  is  not  always  equivalent  to  the  ProDOS  8  system 
prefix's  initial  value. 

The  maximum  length  for  a  prefix  is  64  characters.  The  minimum 
length  for  a  prefix  is  zero  characters;  a  prefix  of  zero  length  is 
known  as  a  null  prefix.  You  set  and  read  prefixes  using  the  calls 
SET_PREFIX  and  GETJPRErTX.  The  64-character  limits  for  the 
prefix  and  partial  pathname  combine  to  create  a  maximum 
effective  pathname  length  of  128  characters. 
Table  6-2  shows  some  examples  of  prefix  use.  The  pathname 
provided  by  the  caller  is  compared  with  the  full  pathname 
constructed  by  ProDOS  16.  The  examples  assume  that  prefix  0/  is 
/VOLUME1/  and  prefix  5/  is  /VOLUMEl  /TEXT.  FILES/ 


Case  illustrated 


Pathname  provided 


Pathname  as  expanded 


Full  pathname  /VOLUMEl /TEXT  .FILES/CHAP  .3       /VOLUMEl /TEXT. FILES/CHAP  .  3 

Implicit  use  Of  prefix  0/       TEXT  .FILES/CHAP  .  3  /VOLUMEl/TEXT  .FILES/CHAP  .3 

Explicit  use  Of  prefix  0/       0/TEXT. FILES/CHAP  .  3  /VOLUMEl/TEXT.  FILES/CHAP  .  3 

Use  Of  prefix  5/  5/CHAP .  3  /VOLUMEl/TEXT  .FILES /CHAP .  3 

Note:  These  examples  assume  that  prefix  0/  is  set  to    /VOLUMEl/  and  that  prefix  5/  is  set  to 

/VOLUMEl /TEXT.  FILES/. 
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Important     When  your  application  Is  launched,  all  nine  prefix  numbers  are 

assigned  to  specific  pathnames  (some  are  meaningful  pathnames, 
and  others  may  be  null  strings).  However,  prefixes  0/  and  2/  may 
nor  have  the  expected  ProDOS  16  default  values- they  may 
reflect  changes  made  by  the  previous  application.  Beware  of 
assuming  any  particular  initial  value  for  any  particular  prefix. 


All  of  these  file  attributes  are  fully 
explained  in  Appendix  A  of  the 
Apple  IIGS  ProDOS  16  Reference 


Creating  and  destroying  files 

A  file  is  placed  on  a  disk  by  the  ProDOS  16  CREATE  call.  When 
you  create  a  file,  you  assign  it  several  properties,  including 

□  pathname 

□  access  attributes  (deletable,  renamable,  writeable,  readable, 
backup-required) 

□  file  type 

□  auxiliary  type 

□  creation  date  and  creation  time 

Once  a  file  has  been  created,  it  remains  on  the  disk  until  it  is 
deleted  (by  using  the  DESTROY  call). 


Opening,  closing,  and  flushing  files 

Before  you  can  read  information  from  or  write  information  to  a 
file,  you  must  use  the  ProDOS  16  OPEN  call  to  open  the  file  for 
access.  The  OPEN  call  returns  a  reference  number  for  the  file.  All 
subsequent  references  to  the  open  file  must  use  its  reference 
number.  The  file  remains  open  until  you  use  the  CLOSE  call  on  it. 

When  you  finish  reading  from  or  writing  to  a  file,  you  must  use  the 
CLOSE  call  to  close  the  file.  CLOSE  writes  any  unwritten  data  from 
the  file's  I/O  buffer  to  the  file,  and  it  updates  the  file's  size  in  the 
directory  if  necessary.  To  access  the  file  again,  you  have  to 
reopen  it. 

FLUSH,  like  CLOSE,  writes  any  unwritten  data  from  the  file's  I/O 
buffer  to  the  file,  and  updates  the  file's  size  in  the  directory. 
However,  FLUSH  keeps  the  file  open. 
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File  levels 

When  a  file  is  opened,  it  is  assigned  a  file  level  according  to  the 
system  file  level.  You  can  determine  the  current  system  file  level 
with  a  GET_LEVEL  call,  and  can  change  the  level  with  a 
SET_LEVEL  call.  When  you  specify  0  as  the  reference  number  in 
the  CLOSE  and  FLUSH  calls,  all  files  having  a  file  level  greater 
than  or  equal  to  the  current  system  file  level  are  closed  or  flushed. 

This  feature  allows  controlling  programs  to  quickly  close  all  files 
associated  with  their  subprograms.  For  example,  when  a  shell 
program  takes  control  of  the  Apple  IIGS,  it  can  execute  a 
GETJLEVEL  call  to  determine  the  current  system  file  level,  then 
execute  a  SET_LEVEL  call  to  set  the  system  file  level  to  a  higher 
level.  Each  file  opened  by  the  shell  and  by  the  programs  that  run 
under  the  shell  is  then  assigned  the  new  file  level  by  ProDOS  16. 

When  the  shell  is  ready  to  quit,  it  can  execute  a  CLOSE  call  with  a 
reference  number  of  0,  and  all  files  opened  under  the  shell  (that 
is,  those  with  a  file  level  equal  to  or  greater  than  the  current 
system  file  level)  are  closed.  The  shell  can  then  execute  a 
SET_LEVEL  call  to  return  the  system  file  level  to  its  previous  value, 
and  finally  execute  a  QUIT  call. 


Reading  and  writing  files 

READ  and  WRITE  calls  to  ProDOS  16  transfer  data  between 
memory  and  a  file.  For  both  calls,  the  application  must  specify 
the  location  in  memory  of  a  buffer  that  contains,  or  is  to  contain, 
the  transferred  data.  When  the  request  has  been  carried  out, 
ProDOS  16  passes  back  to  the  application  the  number  of  bytes 
that  it  actually  transferred. 

A  read  or  write  request  starts  at  a  specific  position  in  the  file,  and 
continues  until  the  requested  number  of  bytes  has  been 
transferred  (or,  on  a  read,  until  the  end-of-file  has  been  reached). 
Read  requests  can  also  terminate  when  a  specified  character  (the 
newline  character  set  by  the  NEWLINE  call)  is  read. 
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LoadOne  is  in  the  source  file 
PAINT.PAS. 


The  HodgePodge  routine  that  reads  files  is  LoadOne,  called  fron 
the  routine  AskUser,  which  itself  is  called  from  DoTheOpen  whe 
the  user  wants  to  open  a  picture  window.  LoadOne  makes  the 
ProDOS  16  calls  OPEN,  READ,  and  CLOSE: 


function     LoadOne:    Boolean; 

var  openBlk    :    OpenRec; 

readBlk    :    FilelORec; 

begin 

LoadOne    :=  FALSE 
WaitCursor; 

pictHndl    :=  NewHandle ($8000, 

myMemorylD, 

0, 

Ptr(0)); 

if  isToolError   then 
Exit; 

HLock (pictHndl); 

openBlk . openPathname  : = 

@myReply . fullPathname; 
openBlk . ioBuffer  :=  NIL; 

OPEN (openBlk); 
if  CheckDiskError (27)  then 
Exit; 


readBlk . databuf f er 
readBlk . requestCount 
readBlk . f ileRefNum 


=  pictHndl"; 

-  $8000; 

=  openBlk . openRefNum; 


READ (readBlk) ; 
if  CheckDiskError (28)  then 
Exit; 

CLOSE (readBlk) ; 
HDnLock (pictHndl) ; 

LoadOne  :=  TRUE; 


end; 


{begin  LoadOne...} 

{ProDOS  16  parameter  blocks...} 
{...defined  in  ProDOS  16  interface} 


{Initialize  value  of  function} 

{put  up  watch  cursor} 

{request  memory  to  hold  the  picture.. 

{HodgePodge's  User  ID} 

{not  purgeable,  no  restrictions} 

{anywhere} 

{If  the  memory  is  unavailable...} 

{...leave  this  subroutine} 

{Lock  handle  so  picture  won't  move} 
{Now  fill  in  parameter  block:...} 

{pathname  from  Std.  File  results...} 
{zero  this  parameter} 

{make  a  ProDOS  16  OPEN  call} 

{If  it  fails  for  some  reason...} 

{...display  error  and  exit} 

{Fill  in  parameter  block  for  READ:.. 

{pointer  to  where  to  put  data} 

{requested  no.  of  bytes  to  read} 

{file's  reference  number} 

{make  a  ProDOS  16  READ  call} 
{If  it  fails  for  some  reason...} 
{...display  error  and  exit} 
{Open  file  no  longer  necessary:...} 
{Make  a  ProDOS  16  CLOSE  call} 
{Unlock  the  handle  until  we...} 
{...need  the  picture  again} 
{function  successfully  completed} 

{end  of  LoadOne} 
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SaveOne  is  in  the  source  file 
PAINT.PAS. 


The  HodgePodge  routine  that  creates  files  and  saves  them  to  disk 
is  SaveOne.  It  is  called  from  the  routine  DoSaveltem   (which 
saves  the  contents  of  a  picture  file  to  disk),  described  under 
"Communicating  With  Files  and  Devices"  in  Chapter  5.  SaveOne 
makes  the  ProDOS  16  calls  CREATE,  DESTROY,  OPEN,  WRITE, 
and  CLOSE: 


procedure  SaveOne  (pi  ct :    Handle); 

var        destroyBlk  :  PathnameRec; 

createBlk  :  FileRec; 

openBlk  :  OpenRec; 

writeBlk  :  FilelORec; 

begin 

destroyBlk .  pathname    :  = 

QmyReply . f ullPathname; 


{begn  SaveOne...} 

{a  ProDOS  16  parameter  block} 
(a  ProDOS  16  parameter  block} 
{a  ProDOS  16  parameter  block} 
{a  ProDOS  16  parameter  block} 


{Put  pathname  from  DoSaveltem...} 
{...reply  record  into  param.  block} 


DESTROY  (destroyBlk)  , 
createBlk .  pathname 


createBlk .  f  Access 
createBlk .  f  ileType 
createBlk .  auxType 
createBlk.  storageType 
createlk . createDate 
createBlk.  createTime 


@myReply . f ullPathname; 
=  $C3; 
=  $C1; 
-  0; 


=  1 
=  0 
=  0 


{Delete  any  existing  file  with 
that  pathname} 

{Put  the  pathname  in  the  block...} 
{...give  it  this  access  value...} 
{...assign  a  file  type  (unpacked)...} 
{..aux.  type  -  0...} 
{...make  it  a  seedling  file...} 
{...let  ProDOS  16  assign...} 
{...creation  date  and  time.} 


CREATE  (createBlk)  ; 
if  CheckDiskError(25) 
Exit; 


then 


{Create  the  new  file} 

{If  the  file  can't  be  created..} 

{...display  error  and  exit} 


openBlk .  openPathname  :  = 

0myReply . f ullPathname; 
openBlk .  ioBuffer   :=  NIL; 


{Put  the  pathname  into  the  block} 
{  (this  field  must  be  zero) } 


OPEN  (openBlk); 

writeBlk.  dataBuffer   :=  pictA; 
writeBlk . requestCount  :=  $8000; 
writeBlk.  fileRefNum   :=  openBlk. 
WRITE  (writeBlk); 
if  CheckDiskError (26)  then 
Exit; 


fileRefNum; 


{Open  the  file  we've  just  created} 
{Make  a  pointer  to  the  buffer...} 
{...from  the  handle  to  the  picture} 
{Transfer  the  entire  32K-byte  file} 
{supply  file's  ref_num} 
{Write  the  data  to  the  file} 
{If  the  file  can't  be  written  to...} 
{...display  error  and  exit} 


CLOSE  (writeBlk); 


{Close  the  file} 


{End  of  SaveOne} 
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Brief  explanations  of  certain 
ProDOS  16  parameters,  such  as 
access  and  file  type,  are  found 
elsewhere  in  this  section. 


The  parameter  lists  for  the  ProDOS  16  calls  used  in  LoadOne  and] 
SaveOne  are  all  combined  into  the  single  record  P16Blk, 
defined  in  the  Pascal  interface  library  to  ProDOS  16.  Complete  ] 
documentation  of  required  parameters  for  all  ProDOS  16  calls  is  | 
in  the  Apple  IIGS  ProDOS  16  Reference. 


The  EOF  and  Mark 

To  aid  reading  from  and  writing  to  files,  each  open  file  has  one 
number  indicating  the  end  of  the  file  (the  EOF),  and  another 
defining  the  current  position  in  the  file  (the  Mark).  ProDOS  16 
moves  (increments  or  decrements)  both  the  EOF  and  the  Mark 
automatically  when  necessary,  but  an  application  program  can 
also  manipulate  them  independently  of  ProDOS  16. 

The  EOF  is  the  number  of  readable  bytes  in  the  file.  The  Mark 
cannot  exceed  the  EOF.  If  during  a  write  operation  the  Mark  meeB 
the  EOF,  both  the  Mark  and  the  EOF  are  moved  forward  one 
position  for  every  additional  byte  written  to  the  file. 

To  move  the  EOF  and  Mark,  use  the  SET_EOF  and  SET_MARK 
calls.  To  determine  the  current  values  of  the  EOF  and  the  Mark 
use  the  GET_EOF  and  GETJMARK  calls. 

♦  HodgePodge:  HodgePodge  doesn't  pay  much  attention  to  EOF 
and  Mark  in  its  file  access,  because  it  reads  and  writes  only 
entire  files  at  a  time. 


For  more  information  on  all  file 
attributes,  see  Appendix  A  of  the 
Apple  IIGS  ProDOS  16  Reference. 


File  attributes 

The  directory  entry  for  each  file  contains  information  that  may 
be  useful  to  your  program.  This  section  describes  the  following 
fields  in  directory  entries  and  headers: 

□  creation  and  last-modification  dates 

□  access  attributes 

□  file  type 

□  auxiliary  type 

If  you  want  to  know  the  properties  of  a  given  file,  use  the 
GET_FILE_INFO  call.  If  you  want  to  change  the  file's  name,  use  the 
CHANGE_PATH  call.  To  alter  the  other  properties,  use  the 
SET_FILE_INFO  call. 
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Creation  and  last- modification  date  and  time 

The  date  and  time  of  creation  of  a  file  are  stored  in  the  file's 
directory  entry.  When  your  program  creates  a  new  file,  ProDOS  16 
automatically  gives  the  file  the  current  system  date  and  time. 
When  your  program  modifies  a  preexisting  file,  ProDOS  16 
automatically  sets  the  last-modification  date  and  time  to  the 
current  date  and  time.  In  general,  your  program  should  not  have 
to  change  these  attributes. 

Access 

The  access  attribute  field,  or  access  byte,  determines  whether  the 
file  can  be  read  from,  written  to,  deleted,  or  renamed.  It  also 
contains  a  bit  that  can  be  used  to  indicate  whether  a  backup  copy 
of  the  file  has  been  made  since  the  file's  last  modification. 

ProDOS  16  sets  the  backup  bit  whenever  the  file  is  changed  (that 
is,  after  a  CREATE,  RENAME,  CLOSE  after  WRITE,  or 
SET_FILE_INFO  operation).  This  bit  should  be  reset  by  a  backup 
utility  (using  CLEAR_BACKUP_BIT)  whenever  it  makes  a  backup 
copy  of  the  file.  No  other  program  should  ever  reset  the  backup 
bit. 

♦  HodgePodge:  When  HodgePodge  creates  its  picture  files,  it 
assigns  them  the  access  value  of  $C3,  meaning  that  they  may 
be  destroyed,  renamed,  read  from,  and  written  to. 

File  type 

The  f  ile_type  field  in  a  directory  entry  identifies  the  type  of 
file  described  by  that  entry.  This  field  should  be  used  by 
applications  to  guarantee  file  compatibility  from  one  application 
to  the  next.  The  currently  defined  hexadecimal  values  of  this  byte 
are  listed  in  Table  6-3. 

Table  6-3  also  lists  the  3-character  mnemonic  file-type  codes  that 
might  appear  in  catalog  listings.  For  any  file  type  without  a 
specified  mnemonic  code,  most  catalog  programs  substitute  the 
hexadecimal  file  type  number. 

SOS  Is  the  operating  system  for  ♦  SOS:  SOS  file  types  are  included  in  Table  6-3  because  SOS  and 

theApple  III  computer.  ProDOS  have  identical  file  structures.  Each  may  read  the 

other's  files. 

♦  HodgePodge:  When  HodgePodge  creates  its  picture  files,  it 
assigns  them  the  file  type  $C1  (picture  file,  unpacked  format). 
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Table  6-3 

ProDOS  file  types 


File  type  Code        Description 


$00 

$01 

$02  * 

$03  * 

$04 

$05  • 

$06 

$07  * 

$08 

$09  * 

$0A  * 

$0B   • 

$0C   * 

$0D-$0E  < 

$0F 

$10  * 

$11   * 

$12  * 

$13  • 

$14  • 

$15  • 

$16-$18  * 

$19 

$1A 

$1B 

$1C-$AF 

$B0 

$B1 

$B2 

$B3 

$B4 

$B5 

$B6 

$B7 

$B8 

$B9 

$BA 


BAD 

PCD 

PTX 

TXT 

PDA 

BIN 

FNT 

FOT 

BA3 

DA3 

WPF 

SOS 

DIR 

RPD 

RPI 


ADB 
AWP 
ASP 

SRC 

OBJ 

LIB 

Sl6 

RTL 

EXE 

PIF 

TIF 

NDA 

CDA 

TOL 


Uncategorized  file  (SOS  and  ProDOS) 

Bad  block  file 

Pascal  code  file 

Pascal  text  file 

ASCII  text  file  (SOS  and  ProDOS) 

Pascal  data  file 

General  binary  file  (SOS  and  ProDOS  8) 

Font  file 

Graphics  screen  file 

Business  BASIC  program  file 

Business  BASIC  data  file 

Word  processor  file 

SOS  system  file 

SOS  reserved 

Directory  file  (SOS  and  ProDOS) 

RPS  data  file 

RPS  index  file 

AppleFile  discard  file 

AppleFile  model  file 

AppleFile  report  format  file 

Screen  library  file 

SOS  reserved 

AppleWorks®  Data  Base  file 

AppleWorks  Word  Proc.  file 

AppleWorks  Spreadsheet  file 

Reserved 

APW  source  file 

APW  object  file 

APW  library  file 

ProDOS  16  application  program  file 

APW  run-time  library  file 

ProDOS  16  shell  application  file 

ProDOS  16  permanent  initialization  file 

ProDOS  16  temporary  initialization  file 

New  desk  accessory 

Classic  desk  accessory 

Tool  set  file 
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Table  6-3  (continued) 
ProDOS  file  types 


File  type 


Code        Description 


$BB 

$BC 

$BD-$BF 

$C0 

$C1 

$C2-$EE 

$EF 

PAS 

$F0 

CMD 

$F1-$F8 

$F9 

$FA 

INT 

$FB 

IVR 

$FC 

BAS 

$FD 

VAR 

$FE 

REL 

$FF 

SYS 

Driver  file 

General  ProDOS  16  load  file 

Reserved  for  ProDOS  16 

Apple  IIGS  picture  file  (packed  formats) 

Apple  IIGS  picture  file  (unpacked  format) 

Reserved 

Pascal  area  on  a  partitioned  disk 

ProDOS  8  CI  added  command  file 

ProDOS  8  user-defined  files  1-8 

ProDOS  8  reserved 

Integer  BASIC  program  file 

Integer  BASIC  variable  file 

Applesoft  program  file 

Applesoft  variables  file 

Relocatable  code  file  (EDASM) 

ProDOS  8  system  program  file 


•apply  to  Apple  III  (SOS)  only 

Auxiliary  type 

Some  applications  use  another  field  in  a  file's  directory  entry,  the 
auxiliary  type  field  (aux_type),  to  store  additional  information 
not  specified  by  the  file  type.  Some  catalog  listings  may  display 
the  contents  of  this  field  under  the  heading  "Subtype." 

For  example,  APW  source  files  (file  type  $B0)  include  a  language- 
type  designation  in  the  aux_type  field.  The  starting  address  for 
ProDOS  8  executable  binary  files  (file  type  $06)  may  be  in  the 
aux_type  field.  The  record  size  for  random-access  text  files  (file 
type  $04)  may  be  specified  in  the  auxiliary  type  field. 
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For  most  file  types,  ProDOS  16  and  ProDOS  8  impose  no 
restrictions  (other  than  si2e)  on  the  contents  or  format  of  the 
auxiliary  type  field.  Individual  applications  may  use  those  two 
bytes  to  store  any  useful  information. 

♦  Hodgepodge:  When  HodgePodge  creates  its  picture  files  it 
assigns  them  an  auxiliary  type  value  of  0.  It  stores  no 
information  in  the  auxiliary  type  field. 


SFGetFile  sends  to  OpenFilter  only 
the  file  types  specified  in  its 
typeLisf  parameter-see 
"Communicating  With  Files  and 
Devices'  In  Chapter  5. 


OpenFilter  Is  in  the  source  file 
PAINT.  PAS. 


Controlling  user  access  to  files 


rlne^r     n  ??  !"d  St0red  by  HodgePodge  are  ProDOS  file 

type  $C1.  Because  HodgePodge  cannot  handle  other  file  types 
*e  user  should  not  be  permitted  to  select  anything  but  $C1 files 

^ot'n"01,  U  ?8ht  be  useful  to  let  the  user  ^  ^ot 
select,  other  files  in  a  directory. 

The  HodgePodge  routine  OpenFilter  is  called  by  the  Standard 

types  fn^neo5  ^  ?'  k  ^  °Ut  h°W  t0  ^  files  of  ^ 
IfcZA        ^     al°8  b°X-  FOf  CaCh  file  entfy  *  encounters, 

nof  d  solave'd   ■   It  r°Utine-  If  ^  rOUUne  retUfnS  °-  the  file—  * 
not  displayed;  if  the  routine  returns  1,  the  filename  appears 

0±mmed)  but  the  file  is  not  selectable;  if  the  routine  returns  2  fc 
filename  is  not  dimmed  and  the  file  is  selectable.  OpenFilter 
dims  all  file  types  but  $C1. 

fierdTn^16/11^7136^"  bdOW  is  a  P°inter  to  ^  Ale-type 

eld  in  the  directory  entry  for  the  file  under  consideration  Tfc 
file-type  field  is  at  an  offset  of  10  bytes  into  the  file  entry 


function  OpenFilter (dirEntryrlongint) : 


type        BytePtr 


Integer;  {begin  OpenFilter...} 


"byte; 


fileTypePtr  :  BytePti 


begin 

fileTypePtr    :=  Pointer    (dirEntry  +   $10) • 

^(BitAND (fileTypePtr*, $00FF)  -  $C1)  then 

OpenFilter  :=  2 
else 


OpenFilter 
end; 


:-  l; 


{First,  get  a  pointer  to  the  file's...} 
file  type  from  its  directory  entry.} 
{If  it's  unpacked  Picture  File  type  } 
{...make  it  black  and  selectable} 
{If  it's  any  other  file  type...} 
{...it's  dimmed  and  nonselectable} 
{End  of  OpenFilter} 
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program  design  and  rt«~5  d  Seilf-™1  ^mis  on 

Tiles  used  durtfw  »florarn  ,  „  '  '  H  XIj  w*  discuss  uV  ivpwtf 

«d  m  «£uek  Sr :;"'.  rr  rilcs'  ""^ 

Apple  (IGS  Pro^rammir^^h^ 

d  shell 

C  editor 

G   linker 
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cor^onen*  of  the  d^HQ5  CF  CU™  and  ^ 

Q  65816  assembler 
n  C  Compiler 
□  bther  compilers 
D   debuggers 


*=taft»!  7,  Cr^ilng  B  fe^*^  App^im 


Utilities 


Program  descriptions 

The  programs  included  in  the  Apple  IIGS  Programmer's 
Workshop  relate  to  each  other  as  illustrated  in  Figure  7-1.  The 
APW  Shell's  command  interpreter  serves  as  the  interface  between 
you  and  the  rest  of  the  Apple  IIGS  system.  The  shell  allows  you  to 
call  the  other  programs  that  constitute  the  Apple  IIGS 
Programmer's  Workshop,  and  serves  as  the  link  between  APW  and 
the  Apple  IIGS  Toolbox  and  operating  system.  The  toolbox  and 
operating  system  (including  ProDOS  16,  the  System  Loader,  and 
the  Memory  Manager)  are  the  interface  between  APW  and  Apple 
IIGS  hardware  and  firmware. 


Apple  IIGS  hardware  &  firmware 


ProDOS  16 


APW  Shell 


Editor 


X 


Linker 


X 


Command  interpreter 


j  j  j  j  j  -i . 


Debugger 


Compilers 


j  j  j  j  j  j  -i  j  j  j  j— i 


HJ 


User 


Figure  7-1 

APW  programs  in  the  Apple  IIgs  system 


Shell 


The  shell  program  is  the  interface  that  allows  you  to  execute  APW 
commands  and  programs.  With  it  you  can  perform  a  variety  of 
housekeeping  functions,  such  as  copying  and  deleting  files  or 
listing  a  directory.  The  shell  supports  input  and  output  redirection 
and  pipelining  of  APW  programs. 
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ProDOS  16  calls  are  described  in 
the  Apple  IIGS  ProDOS  16 
Reference 


The  shell  also  acts  as  an  interface  and  extension  to  ProDOS  16 
providing  several  functions,  called  shell  calls,  that  can  be  called   j 
by  programs  running  under  the  shell.  Shell  calls  can  be  used  by 
utility  programs,  compilers,  linkers,  or  assemblers  to  perform  such] 
functions  as  passing  parameters  and  operations  flags  between  the 
shell  and  APW  programs.  The  format  for  making  these  calls  is 
exactly  like  that  used  for  making  a  ProDOS  16  call. 

Editor 

This  full-screen  text  editor  is  designed  for  use  with  APW 
assemblers  and  compilers.  It  allows  you  to  enter,  copy,  delete,  and 
move  text,  and  provides  automatic  search  and  search-and-replace 
functions. 


Macros  are  commands,  each 
one  of  which  replaces  several 
assembly-language  instructions 
or  assembler  directives.  When  a 
program  is  assembled,  the 
assembler  replaces  macros  with 
their  equivalent  instructions  and 
directives, 


Assembler 

This  full-featured  assembler  allows  users  to  write  65816  assembly- 
language  programs  for  the  Apple  IIGS  computer,  with  complete 
support  for  the  standard  Apple  IIGS  file  format  and  library  files 
The  Apple  IIGS  Programmer'sWorkshop  Assembler  includes 
macros  to  facilitate  assembly-language  programming,  and  allows 
users  to  write  their  own  macros  and  library  files. 

The  APW  Assembler  is  specifically  designed  for  writing  relocatable , 
code,  because  the  APW  Linker,  System  Loader,  and  Memory  Manage; 
are  all  designed  to  work  most  efficiently  with  relocatable  code 


C  Compiler 

The  Apple  IIGS  Programmer's  Workshop  C  Compiler  is  a 
complete  implementation  of  the  C  programming  language  It 
consists  of  a  C  compiler,  the  Standard  C  Library,  the  Apple  IIGS 
Interface  Libraries,  and  the  C  SANE  Library.  The  object  files 
output  by  the  C  compiler  are  fully  compatible  with  those  output 
by  the  APW  Assembler  and  consist  of  relocatable  code. 

Linker 

ImwAf W  Li?er  UkeS  the  files  Ccalled  ^ject  files)  created  by  the 
APW  Assembler  or  any  of  the  APW  compilers,  and  generates  files 
mat  the  System  Loader  can  load  into  memory  {load  files).  The  linker 
resolves  external  references  and  creates  relocation  dictionaries 
which  allow  the  System  Loader  to  relocate  code  at  load  time 
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Although  the  APW  Linker  is  a  single  program,  conceptually  there 
are  two  APW  linkers: 

□  Normally,  the  linker  is  called  directly  by  a  shell  command 
(such  as  the  ASML  command,  which  assembles  and  links  a 
program).  These  commands  provide  a  limited  number  of 
linker  options;  most  linker  options  either  are  not  available  or 
are  set  to  default  values.  In  this  manual,  this  aspect  of  the  linker 
is  referred  to  as  the  standard  linker. 

a  Alternatively,  all  functions  of  the  APW  Linker  can  be  controlled 
by  compiling  a  file  of  linker  commands.  The  linker  command 
language,  called  LinkEd,  allows  you  to  do  such  things  as  place 
specific  object-file  segments  in  specific  load-file  segments, 
create  dynamic  load  segments,  set  load  addresses  for 
nonrelocatable  code,  search  libraries,  and  control  the  output 
printed  by  the  linker.  You  can  compile  and  execute  LinkEd 
commands  separately  from  your  source  code  by  using  the 
ASSEMBLE,  COMPILE,  or  ALINK  commands  of  the  APW  Shell. 
In  this  manual,  the  aspect  of  the  linker  controlled  by  LinkEd 
files  is  referred  to  as  the  advanced  linker. 

The  advanced  linker  is  provided  for  programmers  who  require 
maximum  flexibility  from  the  system;  for  most  purposes,  the 
standard  linker  is  completely  adequate.  When  a  statement  in  this 
book  applies  equally  to  the  standard  and  advanced  aspects  of  the 
APW  Linker,  the  terms  APW  Linker  or  linker  are  used. 

Because  all  Apple  IIGS  Programmer's  Workshop  assemblers  and 
compilers  create  object  code  that  conforms  to  the  same  format, 
the  APW  Linker  can  link  together  object  files  written  in  any 
combination  of  the  development-environment  languages. 

Utility  programs 

The  Apple  IIGS  Programmer's  Workshop  includes  several 
programs,  called  APW  Utilities,  that  perform  functions  not  built 
into  the  shell.  Utilities  include  the  following. 

■  Compact,  which  makes  load  files  more  compact  so  they  load 
faster  and  take  up  less  space  on  disk. 

■  Crunch,  which  combines  multiple  object  files  created  by  partial 
assemblies  or  compiles  into  a  single  object  file. 

■  DumpOBJ,  which  lists  an  object-module-format  file  to  standard 
output  (usually  the  screen). 
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Pre  DOS  8  binary  H,es  are 
executable  sl-qriduro'-App/e 
programs, 


«   E<ix,aj,  which  compares  two  files  or  directs  for  equals  of 
iheir  coil  Lents,  da.i.cis,  and  file  types. 

■  Files,  which  fefe  the  contents  of  a  director^  including 

™J?**  n)es  ^  **>  *«h  for  a  file  wh^  name 
contains  a  string  you  specify. 

■  laltf  which  initialises  $&&$&&  a  disk. 

■  MacGen,  w&eh  &ji**b>*  3  custom  macro  file  for  a  program. 

*  ¥6u^m<Thk:h  creates a PwDOS  e  binaiy  nie  from  *  |JfoD^ 

■  Makt-Lib,  which  create  a  library  file  from  object  fifoa  or 
modifies  an  existing  hlwajry  hid. 


Ine  Apple  fl©3  Debugger  l£ 
documented  In  VneAppfo  m$ 
Debugger  tefarsnea 


Apple  jigs  Debugger 

A^?S  f6  ^bugging  of  pn>sramSt  Apple  Jfles 

£wr  X  W':th  ^  *****  C°^  ^  ***  ** 

pebugger  allows  you  to  trace  or  step  through  a  program  one 

53E2; " a  finie  0f  to  ?ecute  ,/,e  pro**- « ^  > 

™f  y™  c*n  1I15erc  breakpoints  at  which  the  debugger   ag 
cxecuuon  so  that  you  can  i„,peCr  the  contents  of  the  regSe* 
memory,  direct  page,  and  stack.  ' 

2S?^2SS  d?P[ay  3  7? *?  °f  typeS  of'  ***"***  ™  trj 
c2t3  J S  '  Cl,5JSSeJT]hTy  <*  *»  c^e  being  traced,  <he 
£S    h,  "^  ft  "0rmal  diwpLly  of  ,he  P««nun  being 

XStoS  SS       ' IV"*™'*  ***  ***  a*  contend 
Apple  JI0S  registers,  and  Lhc  ,om^  0f  ^  pr ogram>3  sf_aH±_ 

Because the  debugger  can  provide  only  an  assembly-language 
^tmg  of  machine  code,  it  is  niost  usefuJ  for  ^bugging  SSStf 
*rtt»  m  assembly  la  ngu age.  However,  if  Vou  have  a  good 
understanding  of  how  your  high-level-language  program^ 
co^ed  m  machine  code,  you  can  u.fthe  the  dStler  ro 
help  find  the  subrouf  ine  containing  the  problem. 

*  iMtte  The  Apple  lies  Debugger  i$  not  pari  of  APW  [t  is  a 

separaie  pruduci,  available  through  APDA,  See  Chapter  % 
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See  Chapter  9  for  more 
information  on  the  Apple 
Programmer's  and  Developer's 
Association  (APDA). 


Language  considerations 

The  APW  package  includes  a  powerful  65816  assembler.  At  the 
time  of  this  printing,  the  other  languages  available  for  APW 
include  C  and  Pascal.  The  APW  environment  is  designed  to 
support  any  number  of  programming  languages;  check  with  your 
Apple  dealer  and  the  Apple  Programmer's  and  Developer's 
Association  to  find  out  what  other  languages  are  available.  Before 
you  purchase  any  language,  make  sure  that  it  creates  APW- 
compatible  files  and  provides  full  and  convenient  toolbox 
support. 

One  of  the  advantages  of  working  with  APW  is  that  the  object  files 
created  by  any  APW  assembler  or  compiler  are  compatible  with 
those  created  by  any  other  assembler  or  compiler.  This  means 
that  you  can  link  together  routines  written  in  any  combination  of 
APW  languages  to  create  a  program. 

For  example,  you  can  write  an  application  in  a  high-level  language 
such  as  C  or  Pascal,  in  order  to  make  it  portable  to  other 
computers  and  to  speed  up  development  time.  Most 
programmers  find  it  faster  to  write  programs  in  high-level 
languages  than  in  assembly  language.  Once  the  program  is 
complete,  you  can  determine  which  routines  run  most  slowly  and 
then  write  assembly-language  versions  of  only  those  routines  to 
enhance  the  performance  of  the  program. 

♦  Parameter-passing:  The  exact  method  by  which  parameters  are 
passed  is  usually  of  no  concern  to  your  application  as  long  as 
you  work  in  a  single  language — your  language's  interface 
libraries  and  compiler  take  care  of  all  parameter  passing  to 
and  from  the  toolbox  and  among  routines.  However,  if  you  are 
writing  a  segmented  program  where  parameters  are  passed 
between  routines  written  in  different  languages,  you  need  to 
understand  the  parameter-passing  details  of  your  system.  See 
your  language  reference  for  futher  information. 
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Object  module  format  is  defined 
n  the  Apple  IIGS  Programmers 
workshop  Reference. 


The  Apple  IIGS  uses  three  fundamental  types  of  program  files- 
source  files,  object  files,  and  load  files. 

'  foTowe,h?eS  ^  ASCH  filCS  COmiSting  °f  Code  and  ^ta,  and 
follow  the  conventions  of  a  particular  programming  language 

■  Object  files  are  binary  files  created  by  assemblers  and 
compilers;  they  represent  an  intermediate  step  in  the  program- 

mod  P  Trf  Pr°CeSS-  °bJeCt  fiIeS  Camot  be  ™d  and     § 
modified  like  source  files;  neither  can  they  be  loaded  by  the 

S S!m    ?JeCtfileS  Cand  their  do"e  rel^ives,  ££ 
Hies;  are  used  only  as  input  to  the  linker. 

'  ITIT^ re,bincary  filCS  Created  by  ±e  linker-  Load  files  can 

f nhett "'f C  SySt£m  L°aden  ™ey  cannot  be  used  **  *l« 
to  the  linker;  if  you  want  to  link  a  new  routine  to  a  program  yc, 
must  go  back  to  the  object  files  to  do  so. 

There  is  a  single  binary  file  format  used  by  APW  and  the  Apple 

OMFTir8  TT  thC  APP1C IIGS  °b'ect  moduIe  format 

(OMF).  Although  OMF  defines  the  structure  and  record  types  of 

obLtrfdi^r ioad  fiies'  d° not  get  **  *££%** 

object  and  load  hies  are  two  versions  of  the  same  thing  Thev 

serve6  ^^^  °' ?«**■  but  <**«  ^  -™ 
serve  different  purposes  and  are  read  by  different  programs. 


le0cUvees  tn?nSiStS  °^roframmin8^nguage  instructions, 
the  ProSm   Tn  r'  ^    i^  ^^  ^  daU  needed  »* 

labdVcIlSTf'  7?  YOU  ^  t0  CXeCUte  a  -brouJnfsucha 

tjs^'.s^.1*^ (that  is- a  ^o/that  -  - 

In  high-level  programming  languages,  the  use  of  symbolic 
references  is  often  the  only  way  to  jump  from  one  pice in  a 

s:  o°saoneoc  fer-  in  rembiy  ianguage-  °"  **  °™  « 

^f^twh^S 

SSnWc^  SSS£~  -  *  "though  -Lt 
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Absolute  code,  relocatable 
code,  and  the  process  of 
relocation  by  the  System  Loader 
are  discussed  in  more  detail  in 
Chapter  6. 


The  code  created  by  an  APW  compiler  normally  contains  no 
absolute  references,  and  so  need  not  be  loaded  into  a  specific 
location  in  memory.  It  is  referred  to  as  relocatable.  Note  that  this 
term  is  somewhat  misleading:  a  relocatable  program  can  be 
loaded  into  any  location  in  memory,  but  it  cannot  necessarily  be 
moved  once  it  has  been  loaded. 

The  term  relocation  in  this  context  means  the  process  of 
inserting  into  the  program  in  memory  (or  patching)  the  actual 
memory  addresses  to  which  jumps  must  be  made.  Relocation  on 
the  Apple  IIGS  is  done  during  program  load  by  the  System 
Loader. 

When  source  code  is  assembled  or  compiled,  it  is  converted  into 
object  code  containing  machine-language  instructions,  data,  and 
symbolic  references.  Before  the  program  is  actually  run,  the 
symbolic  references  must  be  resolved — they  must  be  replaced 
with  code  that  the  loader  can  use  to  patch  in  the  proper  addresses 
at  load  time.  The  program  that  resolves  the  symbolic  references  is 
the  APW  Linker.  (The  linker  gets  its  name  from  the  fact  that  it  can 
combine,  or  link  together,  several  object  files  to  create  a  single 
load  file.) 


Do  not  write  absolute  code 

The  advantages  of  using  relocatable  code  for  the  Apple  IIGS  are 
considerable.  Relocatable  code  can  be  placed  in  memory  at 
whatever  location  the  Memory  Manager  chooses.  Because  desk 
accessories,  shell  programs,  RAM-based  tool  sets,  and  so  on  are 
placed  in  memory  by  the  System  Loader  and  Memory  Manager, 
absolute  code  is  likely  to  conflict  with  other  code  already  in 
memory.  It  is  very  unlikely  that  your  program  will  have  sole 
control  of  the  computer  when  it  executes. 

Object  module  format  exists  primarily  as  a  specification  for 
relocatable,  segmented  code.  The  Apple  IIGS  System  Loader  and 
the  Memory  Manager  are  designed  to  support  relocatable  code. 
The  APW  Assembler  and  compilers  are  all  designed  to  generate 
relocatable  code.  It  is  easy  to  write  relocatable  code.  Do  not  write 
absolute  code. 
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Four  steps  to  creating  a  program 

The  conversion  of  a  source  file  into  an  executable  program 
loaded  in  memory  is  done  in  four  main  steps,  as  follows  (and 
shown  in  Figure  7-2): 

1.  You  create  one  or  more  source  files  with  a  text  editor.  In  this  step 
you  design  the  program,  create  its  data  structures,  and  write  its  sub- 
routines. The  source  file(s)  may  be  in  one  or  more  APW  languages. 

2.  You  assemble  or  compile  each  source  file.  Depending  on  the  1 
programming  language  used  in  the  source  file,  the  APW 
Assembler,  C  Compiler,  or  some  other  assembler  or  compiler 
processes  the  source  file  to  create  one  or  more  object  files  The 
object  files  contain  65816  machine-language  instructions,  data, 
and  symbolic  references  to  program  routines. 

Object  files,  then,  consist  of  machine-language  instructions  plus! 
unresolved  symbolic  references. 

3.  You  link  the  object  files,  using  the  APW  Linker.  The  linker  com- 
bines all  of  the  object  files  into  a  single  load  file  and  resolves 
symbolic  references.  The  linker  verifies  that  every  routine  refer- 
enced is  included  in  the  load  file;  if  there  are  any  routines  that  the 
linker  has  not  found  when  it  has  finished  processing  all  of  the 
object  files,  then  it  searches  through  any  available  library  files  for 
the  missing  routines.  The  linker  replaces  symbolic  references  with 
entries  in  special  tables  it  creates,  called  relocation  dictionaries. 
The  load  file,  then,  consists  of  blocks  of  machine-language  code 
that  can  be  loaded  directly  into  memory  (called  memory 
Images),  plus  relocation  dictionaries  that  contain  the 
information  necessary  to  patch  address  references  when  the 
program  is  loaded  into  memory. 

4.  You  execute  the  load  file.  It  is  loaded  into  memory  by  the 
System  Loader.  The  loader  calls  the  Apple  IIGS  Memory 
Manager  to  request  blocks  of  memory  for  the  load  file  loads   • 
the  memory  images,  and  uses  the  relocation  dictionaries  to 
patch  the  actual  memory  addresses  into  the  machine-language 
code  in  memory. 

♦  Segments:  The  entire  load  file  is  not  necessarily  loaded  into 
memory  at  one  time;  all  OMF  files  are  divided  into  segments, 
which  can  be  processed  independently.  OMF  file  segmentation 
is  a  fundamental  Apple  IIGS  concept— what  segments  are  is 
discussed  in  Chapters  1  and  6;  how  to  create  them  is 
considered  next. 
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Creating  an  executable  Apple  lbs  program 
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Segments 

When  you  write  a  program,  it  is  generally  considered  good 
programming  practice  to  divide  the  source  code  up  into  smaller 
units  called  subroutines.  Subroutines  make  the  program  easier  to 
write,  read,  and  modify. 

Similarly,  it  is  easier  to  link  a  program  if  the  object  files  are 
divided  up  into  smaller  units.  In  this  case,  we  call  the  units  object 
segments. 

Load  files,  too,  can  be  easier  to  load  into  memory  if  divided  into 
smaller  units.  The  subunits  of  load  files  are  called  load  segments. 


Important     Although  it  is  sometimes  convenient  to  use  the  same  or  related 

divisions  for  subroutines,  object  segments,  and  load  segments,  it  Is 
important  to  keep  in  mind  that  they  need  not  correspond.  An  object 
segment  can  contain  one  to  many  subroutines,  and  a  load 
segment  can  contain  one  to  many  object  segments. 

The  proper  use  of  subroutines  (source-code  segments)  is  a  subject 
for  another  book.  How  to  create  object  segments  and  load 
segments  by  using  APW  is  discussed  in  the  following  sections. 


Defining  object  segments 

Each  APW  language  provides  some  means  for  specifying  in  your 
source  file  the  subroutines  that  will  go  into  each  object  segment, 
and  the  name  of  the  object  segment.  In  some  languages,  such  as 
APW  Assembly  Language,  you  can  specify  the  start  and  end  for 
each  object  segment  and  can  include  any  number  of  subroutines 
within  the  segment.  In  some  languages,  such  as  APW  C,  each 
subroutine  becomes  an  object  segment  and  the  object  segment 
name  is  the  same  as  the  subroutine  name. 

Figure  7-3  illustrates  the  conversion  of  source-file  divisions  into 
object  segments. 
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Assigning  object  segments  in  your  source  code 


About  load  segments 

The  APW  Linker  creates  load  files  from  object  files  and  library 
files.  The  linker  cannot  extract  from  an  object  file  a  portion  of 
code  smaller  than  an  object  segment.  So,  to  the  linker,  the  object 
segment  is  the  fundamental  unit  of  an  object  or  library  file.  The 
load  file  consists  of  one  or  more  load  segments,  each  of  which  is 
loaded  into  memory  separately.  So,  to  the  System  Loader,  the 
load  segment  is  the  fundamental  unit  of  a  load  file. 

Keep  in  mind  that  object  segments  and  load  segments  are 
different  entities.  When  you  link  a  program,  you  tell  the  linker  into 
which  load  segment  you  want  each  object  segment  to  go.  You  can 
assign  any  number  of  object  segments  to  the  same  load  segment. 
You  can  assign  each  object  segment  to  its  own  load  segment, 
place  the  entire  program  into  a  single  load  segment,  or  anything 
in  between. 
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How  many  load  segments? 

It  is  not  generally  necessary  or  desirable  to  divide  a  load  file  up 
into  too  many  pieces,  as  the  loader  must  handle  each  load 
segment  independently.  For  small  programs,  in  fact,  you  may  want 
to  have  a  single  load  segment. 


On  the  other  hand,  it  is  often  desirable  to  have  more  than  one 
load  segment.  Because  two  consecutive  load  segments  do  not  ] 
have  to  be  loaded  into  contiguous  memory  locations,  a 
segmented  program  may  load  into  memory  when  a 
nonsegmented  program  won't  fit.  In  fact,  it  is  necessary  to 
segment  some  programs,  because  the  65816  processor  does  not 
allow  single  blocks  of  program  code  larger  than  64K  to  be  loaded 
(there  is  no  such  restriction  on  blocks  of  data).  Programs  that 
consist  of  segmented  load  files  can  often  be  started  up  more 
quickly  than  unsegmented  programs  because  not  all  the  load 
segments  have  to  be  processed  during  the  initial  load.  Some 
segments  can  be  left  on  disk  until  they  are  needed  (if  ever). 

What  is  the  optimum  number  of  load  segments  for  a  program? 
Only  you  can  answer  this  question  for  your  own  program.  If  it  is  a 
small  program,  all  of  which  must  be  in  memory  for  the  program 
to  run,  a  single  load  segment  might  be  fine.  If  the  program  is  large 
enough  that  machines  with  smaller  amounts  of  memory  might 
have  trouble  loading  it,  several  smaller  segments  might  be  better. 
Fortunately,  you  can  segment  your  load  file  during  the  link  stage 
of  program  development;  if  you  are  not  sure  how  many  load 
segments  will  be  best,  you  do  not  have  to  make  the  decision  while 
you  are  writing  the  source  code. 

Which  segments  should  be  dynamic? 

When  you  specify  load  segments,  you  can  designate  some  as 
dynamic.  A  dynamic  segment  is  loaded  automatically  by  the 
loader  and  Memory  Manager  when  it  is  needed  during  program 
execution.  A  segment  that  is  not  dynamic  is  referred  to  as  static.  A 
static  segment  is  loaded  at  program  boot  time  and  is  never 
unloaded  or  moved  during  execution. 
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Overlays  are  program  segments 
that  are  alternately  loaded  at 
exactly  the  same  memory 
address.  No  two  overlay 
segments  can  be  in  memory  at 
the  same  time,  and  no  other 
program  can  use  that  memory 
range. 


When  the  System  Loader  first  loads  a  program,  it  loads  all  the 
program's  static  segments  and  then  passes  control  to  the 
program.  When  any  part  of  the  program  references  a  routine  in  a 
dynamic  segments,  the  loader  finds  the  dynamic  segment  on  disk 
and  loads  it.  The  dynamic  segment  then  remains  in  memory  for 
as  long  as  the  program  is  running,  unless  the  program  unloads  the 
segment  with  a  System  Loader  call.  Unloading  a  segment  makes  its 
memory  block  purgeable,  so  the  Memory  Manager  can  remove 
the  segment  from  memory  if  it  needs  space  to  load  some  other 
segment. 

One  segment  of  every  program — the  program's  main 
routine — must  be  static.  Any  other  segments  may  also  be  static, 
but  (especially  for  large  programs)  the  system  will  run  more 
efficiently  if  infrequently  used  segments  are  dynamic.  There  are 
several  advantages  to  designating  a  segment  as  dynamic.  Because 
dynamic  segments  are  not  loaded  until  they  are  needed,  for 
example,  the  initial  load  of  a  program  is  faster  if  some  of  the 
segments  are  dynamic.  Also,  if  there  is  a  possibility  that  the 
computer  will  run  out  of  memory  while  your  program  is  running, 
you  can  use  dynamic  segments  to  allow  several  parts  of  the 
program  to  share  the  same  portion  of  memory. 

When  dynamic  segments  share  the  same  general  area  of  memory, 
they  are  similar  to  overlays.  However,  dynamic  segments  are 
much  more  versatile  than  overlays,  because  dynamic  segments 
(assuming  they  are  also  relocatable)  can  be  loaded  at  any 
location  in  memory  when  needed.  Furthermore,  one  segment 
need  not  be  removed  from  memory  to  load  the  next.  A  dynamic 
segment  that  is  not  being  used  is  removed  (purged  by  the 
Memory  Manager)  only  if  the  application  permits  it  (with  an 
unload  call),  and  only  if  the  memory  is  needed  for  something 
else.  Otherwise,  the  segment  remains  in  memory  and  need  not  be 
reloaded  the  next  time  it  is  called. 

For  large  programs,  you  will  probably  want  to  see  what  difference 
it  makes  to  designate  a  particular  segment  as  dynamic.  Sometimes, 
for  example,  it  may  be  more  desirable  to  accept  a  delay  in  the 
initial  load  of  a  program  than  to  have  the  program  pause  while  it 
loads  a  dynamic  segment  during  execution. 
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Figure  7-4 

Assigning  load  segments  in  your  source  code 


If  you  use  the  standard  linker  (that  is,  if  you  do  not  use  a  LinkEd 
file),  the  source-code  load-segment  assignments  are  used  when 
you  link  the  file.  Object  segments  assigned  to  the  same  load 
segment  need  not  be  contiguous  in  the  source  file;  in  fact,  they  do 
not  even  have  to  be  in  the  same  source  file.  The  linker  places  all 
of  the  object  segments  that  have  the  same  load  segment  name 
into  the  same  load  segment. 

♦  Order  of  segments:  The  order  in  which  the  linker  finds  the  load 
segment  names  in  the  source  file  is  the  order  in  which  it  places 
the  load  segments  in  the  load  file.  If  the  order  of  the  load 
segments  in  your  load  file  is  important,  then  you  must  either 
order  your  source  code  accordingly,  or  use  a  LinkEd  file  to  link 
the  program. 

The  advantage  of  the  standard  linker  over  the  advanced  linker  is 
that  the  standard  linker  is  quite  automatic.  You  do  not  have  to  list 
either  the  object  segments  or  the  load  segments  in  the  link 
command.  Library  files  in  the  AP W  library  prefix  are  searched 
automatically,  and  you  can  specify  any  other  library  files  you  wish. 
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Initialization  segments  and  direct- 
page  stack  segments  are 
discussed  in  Chapter  6. 


But  there  are  some  disadvantages  to  the  standard  linker: 

□  You  must  alter  the  source  code  to  alter  load-segment 
assignments. 

□  Some  APW  languages  may  not  allow  you  to  assign  special  load 
segment  types  (such  as  initialization  segments  or  direct- 
page/stack  segments)  in  the  source  code. 

D  All  of  the  object  segments  in  the  source  code  are  linked, 
whether  you  want  to  include  them  in  the  load  file  or  not. 

If  any  of  these  restrictions  cause  a  problem  for  you,  you  can  use 
the  advanced  linker  to  link  the  file,  as  described  next. 


Assigning  load  segments  with  a  LinkEd  file 

The  APW  Linker  can  recognize  both  the  names  of  the  objectL 
segments  in  an  object  file  and  the  names  of  the  load  segments  (if 
any)  to  which  those  object  segments  are  assigned.  You  can  use  a 
LinkEd  file  to  take  advantage  of  this  fact. 

For  example,  suppose  you  have  written,  compiled,  and  linked  a 
program  (using  the  standard  linker),  and  you  find  that  one  load 
segment  is  larger  than  64K.  Because  no  single  block  of  code  larg 
than  64K  can  be  loaded  into  memory,  you  must  break  this  load 
segment  into  smaller  pieces.  Rather  than  changing  the  load 
segment  assignments  in  the  source  code  and  recompiling  the 
program,  you  can  link  the  program  with  the  advanced  linker,  using 
LinkEd  commands  to  specify  the  names  of  load  segments  and  the 
object  segments  that  go  into  each  load  segment. 

Figure  7-5  illustrates  this  process.  Note  that  the  object  file  is 
identical  to  the  object  file  in  Figures  7-3  and  7-4.  Let's  assume  that 
the  unnamed  load  segment  is  too  large.  By  using  a  LinkEd  file,  you 
place  object  segments  DAVE  and  END  into  separate  load  segments, 
named  NANCY  and  LAST,  respectively.  The  code  in  object 
segment  END  has  been  put  at  the  end  of  the  program.  Therefore 
we  have  accomplished  two  things  by  using  the  advanced  linker:  we 
have  split  one  large  load  segment  into  two  smaller  load  segments, 
and  we  have  changed  the  order  in  which  the  code  appears  in  the 
load  file. 
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Assigning  load  segments  with  the  advanced  linker 

The  advanced  linker  gives  you  the  freedom  to  ignore  source-file 
load-segment  assignments  and  to  specify  into  which  load  segment 
each  object  segment  should  go.  It  also  lets  you  specify  special 
segment  types  for  load  segments,  and  the  filename  and  file  type 
of  the  output  file.  On  the  other  hand,  you  must  specify  each  object 
file  to  be  included  and  each  object  segment  to  go  into  each  load 
segment. 

For  small  programs  with  only  a  few  object  segments  or  for  larger 
programs  with  a  simple  load-file  structure,  the  standard  linker  is 
easier  to  use.  If  you  are  developing  a  large  program  with  many 
dynamic  segments  or  with  special  segments  such  as  a  direct- 
page/stack  segment  or  initialization  segments,  the  advanced  linker 
gives  you  much  more  flexibility.  By  changing  the  LinkEd  file,  you 
can  change  the  number  and  sequence  of  load  segments,  the 
object  files  and  object  segments  linked,  and  the  segment  types  of 
load  segments.  For  such  a  program,  it  is  well  worth  the  time  and 
effort  to  learn  how  to  use  the  LinkEd  commands  and  to  write  a 
LinkEd  file. 


Segments 


237 


♦  Note:  In  using  dynamic  segments,  it  is  important  that  the 
volumes  containing  all  needed  segments  and  libraries  be  on 
line  at  run  time.  If  the  System  Loader  cannot  find  a  dynamic 
segment  it  needs  to  load,  execution  halts  and  the  user  is 
requested  to  mount  the  proper  volume. 


A  global  symbol  is  a  label  in  one 
segment  that  can  be  referenced 
in  another  segment,  as  opposed 
to  a  local  symbol,  which  can  be 
used  only  within  the  segment  in 
which  It  is  defined. 


Library  files 

Library  files  are  object  files  whose  segments  contain  routines 
useful  to  many  different  programs.  In  APW,  all  library  files  are  in 
object  module  format,  regardless  of  the  language  of  the  source 
file.  An  Apple  IIGS  library  file  (ProDOS  filetype  $B2)  can 
therefore  be  used  by  a  program  written  in  any  source  language. 
Some  languages,  such  as  APW  C,  come  with  a  set  of  library  files 
used  by  that  language. 

A  library  file  includes  a  special  segment  at  the  beginning  of  the 
file,  called  the  library  dictionary  segment  The  library 
dictionary  segment  is  the  first  segment  of  a  library  file;  it  contains 
the  names  and  locations  of  all  the  global  symbols  in  the  file. 
The  linker  uses  the  library  dictionary  segment  to  find  the 
segments  it  needs. 

When  the  linker  processes  one  or  more  object  files  and  cannot 
resolve  a  symbolic  reference,  it  assumes  that  it  is  a  reference  to  a 
segment  in  a  library  file.  If  you  use  the  standard  linker,  it 
automatically  searches  all  of  the  files  in  the  APW  library  prefix 
(prefix  number  / 2— usually  volume/ APW/ LIBRARIES/,  where 
volume  is  the  volume  name  of  your  boot  disk)  as  well  as  any 
library  files  you  specify  on  the  command  line.  If  you  use  the 
advanced  linker  (that  is,  if  you  use  a  LinkEd  command  file),  the 
linker  searches  only  the  library  files  that  you  specify.  Unless  you 
are  using  the  advanced  linker,  you  do  not  even  need  to  know  the 
names  of  the  library  files  in  order  to  use  them;  the  standard  linker 
automatically  finds  the  files  and  extracts  the  segments  it  needs. 


Creating  library  files 

You  can  create  your  own  library  files  from  one  or  more  object 
files  by  using  the  APW  utility  program  MakeLib.  Figure  7-6 
illustrates  the  library-file  creation  process.  You  specify  one  > 
more  object  files  to  be  included  in  the  library  file.  MakeLib 
concatenates  the  files  and  creates  the  library  dictionary  segment. 
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MakeLib  is  described  in  detail  in 
the  Apple  IIGS  Programmer's 
Workshop  Reference 


The  library  dictionary  segment  makes  it  possible  for  the  linker  to 
search  a  library  file  for  global  symbols  (the  names  of  the 
subroutines  it  contains)  much  more  rapidly  than  it  can  search  an 
object  file.  Consequently,  the  linker  will  search  a  library 
dictionary  segment  several  times  if  necessary  to  find  segments 
referenced  by  other  segments  in  the  library  file,  and  the 
sequential  order  of  the  segments  in  a  library  file  is  not  important. 
But  if  you  use  several  library  files,  the  order  in  which  the  files 
occur  is  important  because  each  is  processed  only  once.  It  is  for 
that  reason  that  MakeLib  allows  you  to  include  several  object  files 
in  a  single  library  file. 


ObjectFile  1 


LibraryFile 


segl 


segn 


ObjectFile  2 


segl 


segn 


ObjectFile  3 


segl 


segn 


MakeLib 


Library 
Dictionary 
Segment 


segl 


segn 


segl 


segn 


segl 


segn 


Figure  7-6 

Creating  a  library  file 

In  addition  to  creating  library  files,  the  MakeLib  utility  allows  you 
to  modify  existing  library  files,  and  even  to  recreate  an  object  file 
that  was  a  component  of  a  library  file. 


Creating  segmented  code:  three 
examples 

This  section  presents  examples  of  segmented  programs.  Three 
small  program  examples  are  provided:  a  program  consisting  of  a 
single,  static  load  segment;  a  program  containing  several  static 
load  segments;  and  a  program  using  dynamic  segments. 
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MAIN 


Note:  These  examples  are  simple,  text-based  sample  programs 
meant  only  to  illustrate  segmentation  concepts.  Your  programs, 
whether  segmented  or  not,  should  be  event-driven,  desktop- 
style  applications. 


A  single,  static  load  segment 

The  following  is  a  typical  sequence  for  writing,  compiling,  and 
linking  a  simple  one-segment  program.  It  has  only  one  START 
directive,  so  only  one  segment  is  created.  The  segment  is  not 
explicitly  made  dynamic,  so  it  is  static. 

1.  Boot  APW  and  set  the  system  language  to  the  language  type  of 
the  source  code  you  intend  to  write.  We  are  going  to  write  a 
simple  assembly-language  file  for  this  example,  so  enter  the 
following  command: 


ASM65816 


Set  the  default  prefix  to  the  subdirectory  you  want  to  use  for 
your  files.  If  your  work  disk  is  called  /MYPROGS,  for  example, 
enter  the  following  command: 


PREFIX    /MYPROGS 


3.  Open  a  file  for  editing.  We  will  call  our  source  file  HW.  Enter  t 
following  command: 


EDIT    HW 


ter  the 


Write  the  source  code  for  your  program.  For  our  example,  type 
in  the  following  program: 


KEEP 

HELLO 

MCOPY 

2/AINCLUDE/M16.UTI 

START 

PHK 

PLB 

WRITELN 

#' Hello  world! ' 

LDA 

#0 

RTL 

END 

Output    filename 
Macro   file 

Beginning   of   segment 
Set   data  bank   equal 

to   code  bank 
Macro   that   writes    string 
Set   error   code   to    0 
Return   to   shell 
End  of    segment 
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See  Chapter  8  for  requirements  for 
shell  applications. 


5.  Press  Apple-Q  to  quit  the  Editor.  When  the  Quit  menu  appears, 
press  S  to  save  the  file  to  disk,  then  E  to  return  to  the  APW 
Shell  command  line. 

6.  To  assemble,  link,  and  execute  the  file  HW,  enter  the  following 
command: 

RON    HW 

The  words  Hello    world!  should  appear  on  the  screen, 
following  the  diagnostic  output  of  the  assembler  and  linker.  If 
they  do  not,  check  your  source  file  for  errors  and  try  again. 

7.  You  now  have  a  file  on  your  work  disk  called  HELLO.  To 
execute  this  program,  enter  HELLO  from  the  APW  Shell 
command  line. 

♦  Note:  This  program  cannot  be  executed  from  a  finder  or 
program  launcher.  It  must  run  under  APW. 


Several  static  load  segments 

It  is  often  desirable  to  write  a  program  that  consists  of  more  than 
one  load  segment.  For  example,  when  there  is  no  single 
contiguous  block  of  memory  large  enough  to  load  an  entire 
program,  the  program  may  still  be  loadable  if  it  is  divided  into 
several  load  segments.  The  program  that  follows  is  divided  into 
three  object  segments,  and  each  object  segment  is  assigned  to  a 
different  load  segment. 

This  program  also  illustrates  a  few  of  the  basic  functions  that 
should  be  performed  by  any  shell  application  before  it  begins  to 
run:  reading  the  User  ID  assigned  to  the  program,  reading  the  ID 
of  the  shell  program  that  launched  it,  and  checking  the  command 
line  for  parameters.  This  sample  program  merely  prints  this 
information  to  the  screen;  an  actual  application  could  do  much 
more: 

□  It  could  use  the  User  ID  in  calls  to  the  Memory  Manager  and 
System  Loader. 

□  It  could  use  the  Shell  ID  to  determine  whether  it  was  launched 
by  the  shell  program  under  which  it  was  designed  to  run.  For 
example,  a  compiler  designed  to  run  under  APW  might  not  be 
able  to  run  under  ProDOS  or  under  another  shell. 

D  It  could  use  the  parameters  on  the  command  line  for  whatever 
purpose  the  shell  application  was  created  to  fulfill. 


Creating  segmented  code:  three  examples 


241 


I 


The  program  listed  below  has  three  segments:  two  that  begin  with 
a  START  directive,  and  one  that  begins  with  a  DATA  directive.  The 
program  assembles  into  the  object  segments  MAIN,   WRITE,  and 
MSG,  which  are  linked  into  the  load  segments  MAIN,  OUTPUT,  and 
LABELS,  respectively.  To  create  the  program,  first  use  the 
following  commands  to  set  the  current  language  to  65816 
assembly  language  and  to  enter  the  editor: 

ASM65816 

EDIT  SAMPLE. SRC 

Then  type  in  the  following  program: 


KEEP 

SAMPLE 

MCOPY 

SAMPLE. MACROS 

MAIN 

START 

MAIN 

* 

SET  UP  ENVIRONMENT 

CLINE 

GEQU 

PHK 

PLB 

0 

STA 

USER_ID 

STY 

CLINE 

STX 

CLINE+2 

PUSHWORD 

USER_ID 

PUSHLONG 

#USERID+1 

PUSHWORD 

#4 

_INT2HEX 

JSL 

WRITE 

RTL 

USER_ID 

ENTRY 

DS 

2 

OSERID 

ENTRY 
STR 

END 

■     i 

WRITE         START  OUTPUT 

*        WRITE  USER  ID  TO  SCREEN 


USING 

MSG 

PUSHLONG 

#USRMSG 

_WRITECSTRING 

PUSHLONG 

tUSERID 

_WRITELINE 

LDA 

CLINE 

ORA 

CLINE+2 

Start  segment 

Define  CLINE  as  direct  page 
Set  data  bank  register  equal  to 

program  bank  register 
Accumulator  holds  User  ID 
X  and  Y  registers  contain 

pointers  to  command  line 
Convert  User  ID  to 

hex  number 

ASCII 

string 
Jump  to  next  segment 


Reserve  space  for  User  ID 

Reserve  space  for  User  ID  ASCII  string 


Start  second  segment 

Use  data  in  data  segment 
Pointer  to  output  string 
Writes  'User  ID  =  ' 
Pointer  to  User  ID  ASCII  string 
Writes  User  ID,  Carriage  Ret 
If  pointer  to 

command  line  =  0, 
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LB1 


LB2 


LB3 


LB4 


BNE 

LB1 

POSHLONG 

#NOLMSG 

_WRITECSTRING 

JSR 

LB5 

/JRITE  SHELL  ID  TO 

SCREEN 

PUSHLONG 

#IDMSG 

_WRITECSTRING 

LDY 

#0 

LDX 

#8 

PHX 

PHY 

POSHWORD 

[CLINE],Y 

_WRITECHAR 

PLY 

PLX 

INY 

DEX 

PHX 

PHY 

CPX 

#0 

BNE 

LB2 

PLY 

PLX 

PUSHWORD 

#$0D 

_WRITECHAR 

WRITE  COMMAND  TO 

SCREEN 

POSHLONG 

#COMMSG 

_WRITECSTRING 

LDY 

#8 

PHY 

LDA 

[CLINE] ,Y 

AND 

#$007F 

CMP 

#'  ' 

BEQ 

LB4 

PHA 

_WRITECHAR 

PLY 

INY 

PHY 

BRA 

LB3 

PUSHWORD 

#$0D 

_WRITECHAR 

WRITE  PARAMETERS 

TO  SCREEN 

PUSHLONG 

#PARMSG 

WRITECSTRING 

no  command  line 
Pointer  to  output  string 
Writes  'No  command  line' 
If  no  command  line,  go  to  end 

Pointer  to  output  string 

Writes  'Shell  ID  =  ' 

Use  Y  for  offset  into  Shell  ID 

Shell  ID  is  8  chars,  use  X  for  counter 

Save  X  on  stack 

Save  Y  on  stack 

Push  next  letter  of  shell  ID  on  stack 

Write  one  char  of  shell  ID 

Pull  Y  from  stack 

Pull  X  from  stack 

Increment  Y 

Decrement  X 

Save  X  on  stack 

Save  Y  on  stack 

Compare  X  to  0 

Return  to  LB2  if  X  not  0 

Pull  Y  from  stack 

Pull  X  from  stack 

Write 

Carriage  Return 

Pointer  to  output  string 

Writes  'Command  is  ' 

Use  Y  for  offset  into  command  line 

Save  Y  on  stack 

Load  next  character  into  accumulator 

Just  look  a  t  low  7  bits 

Test  for  Space  character 

Stop  after  first  space 

Push  next  letter  of  command  on  stack 

Write  one  char  of  command  string 

Pull  Y  from  stack 

Increment  Y 

Save  Y  on  stack 

Return  to  LB3 

Carriage  Return 


Pointer  to  output  string 
Writes  'Parameters  are' 
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LB6 


LB7 
LB5 


PLY 

INY 

LDA 

AND 

BEQ 

PHY 

PHA 

_WRITECHAR 

PLY 

INY 

BRA 

PDSHWORD 

_WRITECHAR 

LDA 

RTL 

END 


[CLINE]  ,  Y 
#$00FF 

LB7 


LB6 
#$0D 

#0 


Pull  Y  from  stack 

Increment  Y 

Load  next  character  into  accumulator 

Test  for  Null 

Stop  after  Null 

Save  Y  on  stack 

Push  next  letter  of  parameters  on  stack 

Write  one  char  of  parameters 

Pull  Y  from  stack 

Increment  Y 

Return  to  LB6 

Carriage  Return 

Set  return  code  to  0 

Return  to  segment  Main  to  end  routine  I 

End  of  segment 


MSG 
IDMSG 

USRMSG 
COMMSG 
PARMSG 
NOLMSG 


DATA 

DC 
DC 
DC 
DC- 
DC 
END 


LABELS  Begin  data  segment 

C1 Shell  ID  is:   ■ , H ' 00 ' 
CUser  ID  is:   ^H'OO' 
H'0A',C' Command  is:   ',H'00' 
H'OA' , C 'Parameters  are:   ',H'00' 
C'No  Command  Line.',H'00' 

End  data  segment 


Press  Apple-Q  to  quit  the  Editor.  When  the  Quit  menu  appears, 
press  S  to  save  the  file  to  disk,  then  E  to  return  to  the  APW  Shell 
command  line. 

The  program  uses  macros  in  several  places,  including  macros  for 
calls  to  the  Integer  Math  Tool  Set  and  the  Text  Tool  Set.  Execute  i 
the  following  command  to  create  a  macro  file  for  the  program: 

MACGEN  SAMPLE. SRC  SAMPLE .MACROS  2/AINCLUDE/M16 . TEXTTOOL  2/AINCLUDE/M1 6  UTIL 
2/AINCLUDE/M16.INTMATH 

To  assemble  and  link  the  program,  use  this  command: 

ASML    SAMPLE 

To  run  the  program,  enter  this  command: 

SAMPLE  ONE  TWO  BUCKLE  MY  SHOE  . 
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The  output  should  look  like  this  (the  actual  User  ID  will  vary,  as  a 
new  one  is  assigned  each  time  the  program  is  run): 

User  ID  is:   1129 

Shell  ID  is:   BYTEWRKS 

Command  is:   SAMPLE 

Parameters  are:   ONE  TWO  BUCKLE  MY  SHOE 


Dynamic  segments 

As  an  example  of  a  program  with  dynamic  segments,  we  can  take 
the  same  multisegment  example  we  just  created  and  make  one 
segment  dynamic.  What's  more,  we  won't  have  to  rewrite  a  single 
line  of  the  program's  code  or  re-assemble  it  to  do  so. 

To  make  the  second  segment  of  the  program  dynamic,  you  can 
link  the  program  with  a  LinkEd  file.  First,  if  you  have  not  done  so 
already,  assemble  the  program  (without  linking  it)  with  the 
following  command: 

ASSEMBLE  SAMPLE 

Use  the  following  commands  to  set  the  current  language  to  the 
LinkEd  language  and  to  enter  the  editor: 

LINKED 

EDIT  SAMPLE. LINK 

Type  in  the  following  LinkEd  program: 

KEEP  SAMPLE 

SEGMENT  MAIN 

SELECT/SCAN  SAMPLE. STD  (MAIN) 

SEGMENT/DYNAMIC  OUTPUT 

SELECT/SCAN  SAMPLE. STD  (WRITE) 

SEGMENT  LABELS 

SELECT/SCAN  SAMPLE. STD  (MSG) 

Press  Apple-Q  to  quit  the  Editor.  When  the  Quit  menu  appears, 
press  S  to  save  the  file  to  disk,  then  E  to  return  to  the  APW  Shell 
command  line. 

Execute  the  following  command  to  link  the  program: 

ALINK  SAMPLE. LINK 
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The  APW  Linker  executes  this  LinkEd  file.  Each  SEGMENT 
command  starts  a  new  load  segment.  Each  SELECT/SCAN 
command  scans  through  the  files  with  the  root  filename 
SAMPLE  .  STD  for  the  object  segment  named  in  parentheses.  The 
load  segment  OUTPUT  is  dynamic.  The  load  file,    SAMPLE, 
contains  four  segments;  the  fourth  load  segment  is  the  Segment 
Jump  Table,  created  by  the  linker. 

When  you  launch  this  version  of  SAMPLE,  the  first  and  third 
segments  are  loaded  immediately,  but  the  second  segment  is  not 
loaded  as  part  of  the  initial  load.  When  the  JSL  to  write  is 
executed,  the  loader  loads  the  second  segment. 

♦  Unloading:  Note  that,  once  loaded,  the  dynamic  segment 
remains  in  memory  throughout  execution  of  the  program.  To 
make  this  segment  available  for  automatic  unloading  by  the 
Memory  Manager,  you  must  include  an  Unload  Segment  call  at 
the  end  of  the  segment. 


Debugging 

A  variety  of  software  instruments  exist  to  help  you  locate  and 
correct  errors  in  your  Apple  IIGS  programs.  Some  are 
sophisticated  and  some  are  simple.  Although  nothing  can  make 
debugging  easy,  the  more  experience  you  gain  with  these  aids,  the 
more  efficiently  you  can  find  and  solve  problems. 


Classic  desk  accessories  are 
described  under  "Supporting 
Other  Desktop  Features"  in 
Chapter  5. 


Debugging  with  desk  accessories 

The  fact  that  Apple  IIGS  code  is  typically  relocatable  can  be  a 
problem  during  debugging.  You  can't  control  where  the  loader 
puts  your  program,  and  once  it  is  in  memory,  you  have  no 
obvious  way  to  locate  it.  How  can  you  debug  something  you  can't 
even  find? 

Loader  Dumper  and  Memory  Mangier  are  two  classic  desk 
accessories  (CDA's)  provided  with  the  Apple  IIGS  Debugger 
(described  later  in  this  section).  They  can  give  you  very  basic, 
and  thus  very  important,  information  on  exactly  where  in 
memory  all  the  parts  of  your  program  are.  Furthermore,  because 
they  are  desk  accessories,  they  are  instandy  available  from  within 
your  program  or  debugger. 


246 


Chapter  7:  Creating  a  Segmented  Application 


Loader  Dumper 

Loader  Dumper  is  a  classic  desk  accessory  that  permits  you  to 
dump  (print  out)  the  System  Loader's  data  structures:  the  Memory 
Segment  Table,  Pathname  Table,  Jump  Table,  Loader  global 
variables,  load-segment  information,  and  other  information  used 
by  the  System  Loader. 

A  principal  use  of  the  Loader  Dumper  is  to  get  your  program's 
User  ID  from  the  Pathname  Table.  Then,  using  Memory  Mangier 
(described  next),  you  can  find  out  where  in  memory  all  your 
program's  segments  are. 

Memory  Mangier 

Memory  Mangier  is  a  classic  desk  accessory  that  can  give  you  a 
listing  of  all  allocated  memory  blocks  with  their  associated  User 
ID's,  sizes,  addresses,  attributes,  and  other  information. 

Most  commonly,  you  would  use  Memory  Mangier  to  inspect  all 
your  programs'  segments  and  buffers  in  memory.  They  are 
identified  by  User  ID,  which  you  might  have  obtained  from 
running  Loader  Dumper.  Once  you  have  found  a  segment  you 
want  to  look  at  more  closely,  you  can  go  directly  from  Memory 
Mangier  into  the  Apple  IIGS  Debugger  or  into  the  Monitor 
program  (described  next),  to  do  detailed  inspection  and 
debugging. 

♦  Note:  Memory  Mangier  also  allows  you  to  execute  Memory 
Manager  calls,  so  you  can  use  it  as  an  exerciser  program,  to 
practice  calls  before  writing  them  into  your  code.  Even  though 
this  is  not  a  direct  debugging  function,  it  is  very  useful  because 
you  need  to  understand  the  Memory  Manager  well.  Memory- 
management  errors  are  among  the  most  common  and  most 
elusive  bugs  on  the  Apple  IIGS. 


Debugging  with  the  Monitor  program 

The  Apple  IIGS  Monitor  program  is  a  set  of  ROM-based  routines 
that  give  the  user  direct  access  to  program  code  in  memory. 
Using  the  Monitor,  you  can  perform  these  tasks: 

□  Inspect  and  modify  the  contents  of  any  location  in  memory,  in 

either  hexadecimal  or  ASCII  format. 
a  Move,  compare,  or  fill  ranges  of  memory. 
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The  Monitor  program  and  how  to 
call  it  are  described  in  the^pp/e 
iigs  Firmware  Reference. 


The  debugger  is  described  in 
detail  in  the  Apple  IIGS  Debugger 
Reference  yy 


□  Search  for  specified  patterns  in  memory 

D  rsr^xr of  vari°us  — ™ 

□  Execute  programs  from  within  the  Monitor. 

□  Disassemble  code  in  memory. 

□  Use  the  mini-assembler  to  assemble  small  programs. 

A  special  convenience  of  the  Monitor  is  that  you  can  call  it  from 
w  hm  the  program  you  are  debugging.  To  do  so,  howeve    you 
mus  make  the  call  from  bank  $00,  and  the  machine  mu *  be  I 
emulation  mode-with  the  Data  Bank  and  Program  BTk  reeL 
set  to  2e     and  with  the  direct  page  equal  to  the  IZo^e  In 2 
words,  the  machme  must  look  exactly  like  a  standard  APPle  IL 
A  second  method  is  to  make  a  Miscellaneous  Tool  Set  call  to 
invoke  the  Monitor.  In  this  case,  the  machine  mus  be  in  Ml 

up  ^emc0a"ecaandbthe  T^  "^  ^  h™  b™d 
up.  the  call  can  be  made  from  anywhere  in  memory. 


Tiinto 


Debu99irl9^^^ 

Zlt"^  !!GS  DebU8ger  allOWS  y°u  to  load  your  program  ir 

th    p  ogrl  exe^t  ^^  *  ^  «*  debu^  -" 
SftSc  '  y°U  Can  examine  ±e  stents  of  the 

SLfmh!  "°r  DebUS8er  Ca"  disPla>'  '"  ^bly-langu,™ 

InZ  so"rcercodeuor  "="<:>«  your  source  code  from  machine 
hn„    Therefore'  the  debugger  is  easiest  ,o  use  with  assembly 

laogfage  to    cToTethe  dyH°U  ^  "°  kn°W'ed8e  °f  ass"»* 
segLot  ,pb"r,£  ^e^'rSra' belter^  " 

P  gee  you  started  debugging  your  program. 
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Debugging  segmented  programs 

In  order  to  use  the  Apple  IIGS  Debugger  to  debug  a  segmented 
program,  you  must  know  where  in  memory  each  segment  has 
been  loaded.  In  the  case  of  a  dynamic  segment,  you  must  know 
whether  it  has  been  loaded  and,  if  so,  where.  This  information  is 
available  through  the  Loader  Dumper  desk  accessory,  described 
earlier  in  this  section. 

To  load  your  program  by  using  the  debugger  and  to  determine 
where  in  memory  each  segment  is  loaded,  use  the  following 
procedure: 

1.  Start  up  the  debugger. 

2.  Use  it  to  load  your  program  into  memory. 

3.  Call  the  Loader  Dumper  from  the  desk  accessories  menu. 

4.  Use  the  Loader  Dumper  to  get  the  User  ID  of  your  program. 

5.  With  that  User  ID,  use  the  Loader  Dumper  to  get  a  listing  of  all 
your  program's  load  segments  and  their  memory  addresses. 

You  now  have  several  possible  courses  of  action  open  to  you.  If 
you  do  not  have  any  idea  in  which  load  segment  your  program  is 
crashing,  you  can  start  by  running  the  program  until  it  crashes 
and  then  examining  the  debugger  display  to  determine  the 
location  of  the  problem  instruction.  If  you  know  in  which  segment 
the  problem  lies,  you  can  go  immediately  to  that  segment,  or  you 
can  set  a  breakpoint  at  the  beginning  of  that  segment  and  run  the 
program  until  it  stops  automatically  at  that  breakpoint. 

Watching  a  running  disassembly 

If  your  program  does  not  require  any  input  from  the  keyboard, 
you  can  watch  a  disassembly  on  the  debugger  screen  as  the 
program  executes  to  find  the  exact  location  at  which  it  goes 
astray.  This  technique  will  probably  be  useful  only  for  short 
programs  or  programs  that  crash  almost  immediately  upon 
execution,  because  the  program  will  execute  very  slowly  while  the 
debugger  display  is  on  the  screen. 

To  run  your  program  under  control  of  the  Apple  IIGS  Debugger, 
with  a  running  disassembly  appearing  on  the  screen,  use  the 
following  procedure: 

1.  Load  your  program  with  the  debugger. 
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2.  Put  the  debugger  in  single-step  mode,  starting  at  the  first 
instruction  of  your  program.  Watch  the  contents  of  the  registers 
and  the  stack  (and  any  specific  memory  locations  you  have 
specified)  as  you  execute  individual  commands. 

3.  You  can  leave  single-step  mode  and  execute  commands 
automatically  in  quick  succession  by  entering  trace  mode.  YoJ 
program  will  begin  executing  under  debugger  control,  one 
instruction  at  a  time  in  rapid  succession.  Once  in  trace  mode, 
you  can  stop  execution  at  any  time  and  then  return  to  single- 
step  mode 


In  trace  mode,  when  your  program  executes  a  BRK  instruction 
execution  stops.  The  last  instruction  executed  (the  BRK 
instruction)  is  displayed  on  the  screen,  along  with  the  previous 
several  instructions  executed.  A  BRK  instruction  is  actually  a  nullL 
(a  zero  byte);  because  such  an  instruction  is  not  a  normal  part  of  1 
a  program,  the  fact  that  your  program  executed  one  probably 
means  that  some  previous  instruction  sent  the  program  off  to  the 
wrong  place  in  memory.  With  luck,  the  instruction  that  sent  your] 
program  off  into  Never  Never  land  will  still  be  on  the  screen. 

Using  breakpoints 

If  you  have  to  interact  with  your  program  in  order  for  it  to  run,  if 
you  have  some  idea  of  which  segment  contains  the  bug,  or  if  you 
just  want  to  execute  the  program  more  quickly,  you  can  set  one  or 
more  breakpoints  before  running  the  program.  A  breakpoint  is  a 
location  at  which  the  debugger  suspends  execution  of  the 
program,  giving  you  the  opportunity  to  examine  the  disassembl 
and  the  state  of  the  machine  at  that  location. 

To  set  breakpoints  and  run  the  program  under  debugger  control, 
try  the  following  procedure: 

1.  Load  your  program  with  the  debugger. 

2.  As  described  above,  use  the  Loader  Dumper  routine  to 
determine  the  starting  locations  of  the  load  segments  of  your 
program. 

3.  Back  in  the  debugger,  set  breakpoints  at  the  beginning  of  each 
load  segment  (if  you  do  not  know  in  which  segment  the  bug 
lies)  or  at  the  beginning  of  any  segment  that  you  want  to 
examine  more  closely. 
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4.  Run  your  program  under  debugger  control,  with  the  debugger 
display  turned  off.  When  the  debugger  comes  to  a  breakpoint, 
the  program  halts  and  the  debugger's  display  appears  on  the 
screen,  showing  the  location  of  the  instruction  at  which  the 
program  stopped  and  other  pertinent  information.  You  can 
also  view  a  disassembly  of  the  program,  starting  at  the 
breakpoint  location. 

5.  While  at  a  breakpoint  you  can  switch  to  single  step  mode.  Step 
through  the  segment  one  instruction  at  a  time  while  watching 
the  contents  of  the  stack,  the  machine's  registers,  and  up  to  19 
memory  locations  you  specify.  From  single-step  mode,  you  can 
return  to  executing  the  program  automatically. 

If  at  any  time  during  execution  of  the  program  a  dynamic  segment 
is  loaded,  you  can  pause  execution  of  your  program  and  go  back  to 
Loader  Dumper  to  find  out  where  in  memory  it  has  been  placed. 

Breakpoints  can  be  used  for  purposes  other  than  finding  a 
particular  segment.  Suppose,  for  example,  that  your  program 
seems  to  run  all  right  for  awhile,  then  crashes  after  having  lulled 
you  into  a  false  expectation  of  success.  In  this  case,  it  is  possible 
that  some  routine  is  failing,  not  the  first  time  it  is  run,  but  only 
after  going  through  several  iterations.  To  handle  such  a  situation 
without  stopping  the  program  every  time  the  routine  is  executed, 
you  can  include  a  trigger  value  for  a  breakpoint.  The  debugger 
counts  the  number  of  times  it  encounters  the  breakpoint,  and 
suspends  execution  only  when  the  trigger  value  is  reached. 

If  you  must  execute  a  routine  at  full  speed  in  order  for  it  to  work 
correctly,  you  can  insert  real  breakpoints  into  the  code.  When  you 
do  so,  the  debugger  actually  inserts  BRK  instructions  into  memory 
at  the  breakpoint  locations.  Trigger  values  work  for  real 
breakpoints  that  you  have  set;  the  debugger  will  still  suspend 
execution  any  time  it  encounters  a  BRK  instruction  that  you  did 
not  set  as  a  breakpoint. 
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Using  memory  protection  ranges 

It  may  be  that  certain  portions  of  your  code  must  be  executed  atj 
the  full  speed  of  the  65816  microprocessor.  To  cause  this  to 
happen  automatically  every  time  you  trace  through  the  program! 
you  can  set  any  areas  of  memory  you  choose  as  code  trace 
ranges.  When  the  program  executes  a  jump  to  a  location  within  i 
code  trace  range,  the  debugger  relinquishes  control  to  yourJ 
program  and  the  code  is  executed  at  full  speed.  The  portion  of 
memory  used  to  run  tool  calls  is  automaucally  set  as  a  code  trao 
range  when  you  load  the  debugger. 

You  can  also  set  one  or  more  portions  of  memory  (the  limits  of 
your  code  as  revealed  by  Loader  Dumper,  perhaps)  as  code- 
window  ranges.  If  the  program  attempts  to  execute  code  outside 
the  code-window  ranges  you  have  set,  execution  stops.  You  might ] 
want  to  set  a  code-window  range,  for  example,  if  your  program  is  j 
executing  a  jump  to  some  incorrect  memory  location  and   ] 
trashing  memory  before  it  stops,  forcing  you  to  reboot  the  L 
machine  every  time  you  try  to  run  the  program  with  the  debugger, 

If  your  program  loads  a  dynamic  segment  during  execution  and 
you  want  to  pause  as  soon  as  control  is  transferred  to  the  dynamic 
segment,  you  can  set  code  window  ranges  to  include  all  the  static 
segments  at  the  start  of  the  program.  Then  when  the  dynamic 
segment  is  loaded  and  control  is  transferred  to  it,  the  program 
will  be  outside  any  code  window  range  and  execution  will  stop. 


Important 


Once  you  have  set  any  code-window  range,  no  code  will  be 
executed  that  is  not  In  a  code-window  range.  Therefore,  if  you  sett, 
code-window  range  equal  to  the  memory  location  of  one  of  your 
program  segments,  you  must  set  code-window  ranges  for  all  other 
segments  that  it  calls. 


Debugging  multiple-language  programs 

One  of  the  advantages  of  using  the  APW  development 
environment  is  that  it  allows  you  to  link  together  routines  written 
in  different  programming  languages.  This  facility  can  lead  to 
unique  problems,  however,  especially  when  information  is  passed 
between  routines  written  in  different  languages. 
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Parameter  passing  may  fail  in  your  program  for  any  of  several 
reasons:  you  might  have  used  a  wrong  variable  type,  for  example, 
or  a  called  routine  might  expect  to  receive  parameters  in  a 
different  order  from  the  way  they  were  passed  by  a  calling  routine. 

To  use  the  Apple  IIGS  Debugger  to  debug  parameter-passing 
problems,  use  the  following  procedure: 

1.  Set  breakpoints  at  the  beginning  of  the  calling  segment  and  at 
the  beginning  of  the  called  segment. 

2.  Run  the  program  in  trace  or  real-time  mode  until  the  first 
breakpoint  is  reached.  Search  this  segment  to  find  the  JSL  that 
calls  the  other  segment. 

3.  Set  a  breakpoint  just  before  the  JSL  that  calls  the  second  segment. 
You  can  remove  the  other  two  breakpoints  now  if  you  wish. 

4.  Run  the  program  until  the  JSL  breakpoint  is  reached. 
Parameters  are  normally  passed  either  on  the  stack  or  in  the  A, 
X,  and  Y  registers.  The  actual  information  passed  may  be  a 
pointer  to  the  data  rather  than  the  data  itself.  By  examining  the 
contents  of  the  registers,  the  stack,  and  memory,  determine  the 
location  of  the  parameter  being  passed,  and  see  if  it  has  the 
value  you  expect. 

5.  Execute  the  JSL.  The  return  address  should  have  been  added  to 
the  stack. 

6.  Step  through  the  segment  in  single-step  mode.  Is  the  called 
routine  reading  the  parameters  passed  to  it,  in  the  proper  form 
and  order?  By  a  careful  study  of  the  action  of  the  called 
routine,  you  should  be  able  to  determine  the  source  of  the 
problem. 

7.  If  all  parameters  are  being  passed  correctly,  perhaps  the 
problem  occurs  when  the  results  are  passed  back  to  the  calling 
routine.  Find  the  RTL,  and  study  the  stack  and  registers  as 
before  to  determine  whether  the  results  are  being  passed 
correctly  back  to  the  calling  routine. 


The  ProDOS  16  Exerciser  is  on  the 
disk  that  accompanies  the  Apple 
IIGS  ProDOS  16  Reference 


The  ProDOS  16  Exerciser 

The  ProDOS  16  Exerciser  is  a  program  that  allows  you  to  practice 
making  operating  system  calls  in  a  controlled  environment, 
before  coding  them  into  your  applications. 
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The  ProDOS  16  Exerciser  is  not  really  a  debugging  tool,  but  you 
can  use  it  in  several  ways  during  the  debugging  process.  For   j 
example: 

a   By  practicing  the  ProDOS  16  calls  you  intend  to  use  in  your 
program,  you  can  "debug"  them  in  the  sense  that  you  can  see 
exactly  how  they  function,  before  writing  them  into  your  code. 

□  Because  the  Exerciser  gives  you  direct  access  to  file  attributes, 
you  can  use  it,  for  example,  to  change  file  types  (such  as  from 
$B5  to  $B3)  without  having  to  enter  APW. 

□  The  Exerciser  allows  you  to  inspect  and  modify  the  contents  of 
any  portion  of  memory,  and  any  block  on  a  disk — but  see  the 
warning  below. 

□  The  Exerciser  allows  you  to  enter  the  Monitor  program 
directly.  Once  in  the  Monitor,  you  can  use  its  debugging 
facilities,  as  described  earlier. 


Warning      The  ProDOS  16  Exerciser  allows  you  unconstrained  use  of  all  ProDOS 
16  calls.  Including  those  that  modify  disk  directories  and  blocks.  It 
also  permits  you  to  modify  any  portion  of  memory,  including  that 
occupied  by  system  software  or  by  the  Exerciser  Itself.  You  can 
easily  destroy  the  contents  of  a  disk  or  cause  a  system  crash.  Be 
careful  what  you  modify! 
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Chapter  8 


What  Type  of  Program 
to  Write? 
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A  list  of  all  defined  file  types  is 
given  under  "The  ProDOS  File 
System"  in  Chapter  6 


Under  ProDOS  16  on  the  AnnlP  rrr<:  „ 

classified  by  file  tvoe  w r     ?    COmPuter>  Programs  are 

of  Pro,rJsZ^^C:!lWdn8  ^  f°ll0Wi^  *» 
this  chapter'  C  Unique  flle  ^P**-  are  given  in 

□  general  applications  (file  type  $B3) 

a  controlling  programs,  such  as  shells,  switchers,  and  operate 

D  TJSSTIS  Cfi'e  ^  $B5)!  **  *  P^  d^d  io 
°  desk  acc^sories  (file  types  $B8  and  $B9) 
o  initialization  files  (file  types  $B6  and  $B7) 

□  interrupt  handlers 

□  user  tool  sets  (file  type  $BA) 

£££?<££  S3)bo0nly  Ho"66"  T^  **  *""> 
writing  so«l^B^0^2i  2°U  3re  imereSted  ^ 
information  in  this  chapter  c^X^ZST^  ** 
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^^^ss^rr a  complete  pr°8ram-  « 

communicate  dreah^ wi  h         "  1"°^  Pr°gram)'  that  ^ 
it  needs.  F^exampfe  worZ  ^'^  SyStGm  S°ftware  °r  firmware 
and  language  in ZoretZ  L? ZT^  Spreadsheet  P^grams, 
code  files,  a8s  ^JSXZS^^^  *?  Md  ""* 
accessories,  and  utilities  that  ^^^^Zt?"1  ** 
are  not  applications.  °m  other  Programs, 
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To  be  a  (stand-alone)  application.,  an  Apple  IK5S  program  nv,c>As 

to  meet  certain  requirements.  Jl.  must 

a   consist  of  executable  machine-language  code 

r   lx:  in  Apple  IIG5  object  module  formal 

n  havo  a  file  type  of  $B3 

n   use.  1'YnDOS  16  as  i Li  operating  system 

J   observe  1.1  it:  ProDOS  \6  QUIT  conventions 

□   gel  all  needed  memory  from  the  Memory  Manager 

All  other  aspects  of  the  program  arc  up  to  you.  But  of  courts  wi: 
sl.nmgly  recommend  tbat  yon  design  your  progams  to  use  the 
Apple  desklop  intciface  and  follow  the  Apple  Human  Interface 
Guidelines. 

<r  l^roDOS  >3r  The  above  list  refers  specifically  to  Apple  IICS 
applications  thai  n.m  under  ProDOS  16,  Rcquiremenl.s  for 
programs  that  run  under  ProDOS  8  arc  quite  different;  see  ihe 
PrvnQS  tf  Technical  Reference  Manual 


PruDOS  s  system  piogrcms  atv 
described  In  tfie  RroOOS  fl 
Technical  Reference  Manual. 


For  a  more  detailed  description  of 
System  5 1  ur  I  up,  see?  the  Appls  tics 
Ratios  16  Geferencst, 


Make  it  self -booking? 

There  are  two  ways  lo  maki:  your  type  SB  3  application  self- 
booting,  so  that  it  is  automatically  luatled  aud  launched  at  system 

Startup: 

n   Give  it  the  filename  extension  .  svsifi.  By  using  this  method, 
your  program  Ixioihikis  a  ProDOS  i6  equivalent  to  a  ProDOS  8 
JSysYem  program  on  a  standard  Apple  II  computer. 

D  Give  it  the  filename  start  and  place  it  in  the  system/ 
subdirectory.  By  using  this  method;  your  progiam  substitutes 
for  1  he  finder  or  program  launcher  that  normally  executes  fin-t 
on  the  Apple  IftSS 

In  either  case,  your  proftam  must  be  the  fi.rsl  (or  only)  program 
with  the  proper  filename  or  filename  extension  that  the  boot 
loader  program  encounters  on  [he.  beol.  disk.  Figure  8-1  diagrams 
the  program  selection  sequence  at  system  stanup. 
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(Boot  sequence: 

the  file  named 

PRODOS  is  executing!) 


Is  there  a  file  named 
/V/SYSTEM/START? 


yes     no 


Is  there  a  .SYSTEM 
or.SYS16file? 


yes     no 


Which  found  first? 


.SYS16  file  found  first 


Execute  a 

ProDOS  16 

QUIT  call, 

using  the 

filename 

of  the 

.SYS16 

program 


(.SYS  16  program  executes) 


Fatal  error 


.SYSTEM  file  found  first 


Execute  an 

enhanced 

ProDOS  8 

QUIT  call, 

using  the 

filename 

of  the 

.SYSTEM 

program 


(.SYSTEM  program  executes) 


load  and 
execute 


/V/SYSTEM/START 


START  is  typically 

a  program 
selector/finder 

Figure  8-1 

Startup  program  selection 

♦  Note:  Apple  recommends  that  you  do  not  name  your 

application  START— leave  that  name  for  a  program  launcher 
or  finder.  If  you  give  your  program  a  clearly  identifiable  name, 
the  user  can  more  easily  launch  it  from  any  boot  disk. 
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Make  it  restartable? 


The  concepts  of  dormant  and 
restartable  programs  are 
discussed  under  "Loading 
Programs  and  Segments"  in 
Chapter  6. 


For  more  information  on  the  APW 
C  language,  see  the  Apple  IIGS 
Programmer's  Workshop  C 
Reference 


If  you  want  your  program  to  be  able  to  be  quickly  relaunched 
from  a  dormant  state  in  memory,  it  needs  to  be  restartable.  A 
restartable  program  reinitializes  all  its  variables  each  time  it  gains 
control,  without  having  to  read  in  files  or  segments  from  disk.  It 
also  makes  no  assumptions  about  the  state  of  the  computer,  such 
as  register  contents  or  flag  settings,  when  it  gains  control.  If  all 
initialization  information  is  in  code  statements  in  your  program's 
initialization  segments  and  static  code  segment(s),  the  program 
should  be  restartable. 

It  is  difficult  for  programs  in  some  languages  to  be  restartable.  In 
C,  for  example,  all  global  variables  are  in  segments  named 
-GLOBALS  and  -ARRAYS,  which  must  be  initialized  each  time  the 
program  starts  up.  To  get  around  this  difficulty,  the  System  Loader 
supports  the  concept  of  RELOAD  segments.  A  RELOAD  segment  is 
a  static  data  segment  that  is  loaded  from  disk  whenever  an 
(otherwise)  restartable  program  is  launched  from  a  dormant  state. 
It  contains  whatever  initialized  data  is  needed  by  the  program;  the 
rest  of  the  program's  static  segments  (other  than  initialization 
segments)  are  not  loaded  at  that  time. 

When  your  application  quits,  it  passes  a  parameter  to  ProDOS  16 
(and  thence  to  the  System  Loader)  stating  whether  the  application 
is  restartable  or  not.  You  must  determine  when  you  write  the 
program  what  type  it  really  is;  neither  ProDOS  16  nor  the  System 
Loader  will  check. 


Programs  that  run  under  shells  are 
called  shell  applications  and  are 

file  type  SB5. 


Controlling  programs 

A  controlling  program  is  a  program  that  loads  and  executes  other 
programs  while  itself  remaining  active  in  memory.  An  application 
needs  to  be  a  controlling  program  only  if  it  must  remain  in 
memory  after  it  calls  another  program.  The  APW  Shell  is  a 
controlling  program;  ProDOS  16  is  a  controlling  program. 

Writing  a  controlling  program  is  far  more  involved  than  writing 
an  application.  This  book  does  not  show  you  how  to  write  a 
controlling  program;  but  if  you  do  write  one,  please  follow  the 
guidelines  below.  They  specify  how  your  controlling  program 
communicates  with  shell  applications.  See  also  the  next  section, 
"Shell  Applications,"  for  more  information  on  how  controlling 
programs  and  their  subprograms  interact. 
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ProDOS  16  register  and  direct- 
page/stack  conventions  are 
discussed  under  "Setting  Up 
Direct-Page/Stack  Space"  in 
Chapter  6,  and  fully  described  In 
the  Apple  IIGS  ProDOS  16 
Reference 


See  "Quitting  and  Launching 
Under  ProDOS  16."  in  Chapter  6. 


a  Your  controlling  program  should  use  the  System  Loader's 
Initial  Load  function  to  load  the  subprogram.  Initial  Load 
returns  the  subprogram's  starting  address  and  User  ID  to  your 
controlling  program.  When  your  controlling  program  passes 
execution  to  the  subprogram,  it  should  pass  the  subprogram's 
User  ID  in  the  accumulator. 

□  Your  controlling  program  may  also  pass  parameters  and  an 
identifier  string  to  the  subprogram,  as  described  under  "Shell 
Applications." 

□  Your  controlling  program  is  responsible  for  establishing  the 
appropriate  input  and  output  vectors  for  its  subprograms.  For 
example,  when  ProDOS  16  launches  a  program,  it  initializes  the 
Text  Tool  Set  to  use  the  Pascal  I/O  drivers  for.  the  keyboard  H 
and  80-column  screen. 

D  Unless  all  its  subprograms  include  direct-page/stack  segments, 
your  controlling  program  must  provide  a  default  direct- 
page/stack  space  for  any  subprogram  that  it  launches.  The 
controlling  program  should  observe  the  ProDOS  16 
conventions  for  register  initialization  and  direct-page/stack  I 
allocation. 

□  Shell  applications  can  terminate  with  either  an  RTL  instruction 
or  a  ProDOS  16  QUIT  call.  If  any  of  its  subprograms  might  uH 
QUIT,  your  controlling  program  must  intercept  all  ProDOS  16 
calls  so  that  when  the  subprogram  quits,  the  controlling 
program,  rather  than  ProDOS  16,  regains  control. 

□  Your  controlling  program  is  totally  responsible  for  disposinj 
of  the  subprogram.  When  the  subprogram  is  finished,  the 
controlling  program  must  remove  it  from  memory  and  release 
all  memory  resources  associated  with  its  User  ID.  The  best  wm 
to  do  this  is  to  call  the  System  Loader's  User  Shutdown 
function.  If  the  program  ends  in  a  QUIT  call,  your  controlling 
program  is  responsible  for  performing  any  other  system  tasks 
normally  done  by  ProDOS  16  in  response  to  a  QUIT. 


. 
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See  "Loading  Programs  and 
Segments"  In  Chapter  6  for  a 
discussion  of  controlling 
programs  and  the  System 
Loader's  Initial  Load  function. 


See  an  example  of  reading  an 
Identifier  string  in  the  second 
sample  program  under  "Creating 
Segmented  Code:  Three 
Examples"  In  Chapter  7. 


Shell  applications 

Shell  applications  (ProDOS  16  file  type  $B5)  are  executable  load 
files  that  are  run  under  a  controlling  program  such  as  the  APW 
Shell.  The  controlling  program  launches  the  shell  application  by 
calling  the  System  Loader's  Initial  Load  function,  and  transfers 
control  to  the  shell  application  by  means  of  a  JSL  instruction, 
rather  than  launching  the  program  through  the  ProDOS  16  QUIT 
function.  Therefore  the  shell  does  not  shut  down,  and  the 
program  can  use  shell  facilities  during  execution. 

A  shell  application  typically  returns  control  to  its  shell  with  an 
RTL  instruction.  With  a  shell  (such  as  the  APW  Shell)  that 
intercepts  ProDOS  16  calls,  the  shell  application  can  end  with  a 
ProDOS  16  QUIT  call. 

Shell  applications  should  use  standard  Text  Tool  Set  calls  for  all 
nongraphics  I/O;  the  controlling  program  is  responsible  for 
initializing  the  Text  Tool  Set  routines. 

♦  Stand-alone:  A  shell  application  can  run  alone  under  ProDOS 
16  if  it  requires  no  support  other  than  standard  input  from  the 
keyboard  and  output  to  the  screen.  ProDOS  16  initializes  the 
Text  Tool  Set  to  use  the  Pascal  I/O  drivers  (discussed  in  the 
Apple  IIGS  Toolbox  Reference)  for  the  keyboard  and  80- 
column  screen.  To  be  launched  this  way,  a  program  must  first 
be  changed  to  file  type  $B3,  and  it  must  end  with  a  ProDOS  16 
QUIT  call. 

As  soon  as  a  shell  application  is  launched,  it  should  save  the  value 
of  its  User  ID,  passed  in  the  accumulator  from  the  controlling 
program.  It  should  also  check  the  X  and  Y  registers  for  a  pointer 
to  the  shell-identifier  string  and  input  line.  The  X  register  holds 
the  high-order  word  and  the  Y  register  holds  the  low-order  word 
of  this  pointer.  The  controlling  program  is  responsible  for 
loading  this  pointer  into  the  index  registers  and  for  placing  the 
following  information  in  the  area  pointed  to: 

n  An  8-byte  ASCII  string  containing  an  identifier  for  the  shell. 
The  identifier  for  the  APW  Shell,  for  example,  is  BYTEWRKS. 
The  shell  application  should  check  this  identifier  to  make  sure 
that  it  has  been  launched  by  the  correct  shell,  so  that  the 
environment  it  needs  is  in  place.  If  the  shell  identifier  is  not 
correct,  the  shell  application  should  write  an  error  message  to 
standard  error  output  (normally  the  screen),  and  exit  with  a 
ProDOS  16  QUIT  call  (if  the  controlling  program  supports  it) 
or  an  RTL. 
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For  more  information  on  direct 
page  and  stack  allocation,  see 
"Setting  up  Direct-Page/Stack 
Space"  in  Chapter  6.  See  also  the 
Apple  IIgs  ProDOS  16  Reference 


□  A  null-terminated  ASCII  string  containing  the  input  line  for  the 
shell  application.  The  shell  can  strip  any  I/O  redirection  or 
pipeline  commands  from  the  input  line,  because  those 
commands  are  intended  for  the  shell  itself,  but  must  pass  on  all 
input  parameters  intended  for  the  shell  application. 

♦  ProDOS  16:  ProDOS  16  does  not  support  the  identifier  string 
or  input  line  convention.  When  an  application  is  launched  by 
ProDOS  16,  the  X  and  Y  registers  contain  zeros. 

If  the  shell  application  does  not  have  a  direct-page/stack  segment, 
it  can  expect  the  controlling  program  to  provide  a  1024-byte 
memory  block  in  bank  $00  for  the  shell  application  to  use  for  its 
direct  page  and  stack.  Whether  the  shell  application  specifies  a 
direct-page/stack  segment  or  accepts  the  default,  the  address  of 
the  start  of  the  direct-page/stack  segment  should  be  in  the  direct 
register  CD),  and  the  stack  pointer  (S  register)  should  point  to  the 
last  (highest-address)  byte  of  the  block  containing  the  direct- 
page/stack  segment. 

Some  shell  applications  may  launch  other  programs;  for  example 
a  shell  nested  within  another  shell  would  be  a  controlling 
program  as  well  as  a  shell  application.  Such  an  application  must 
follow  the  conventions  for  both  types  of  programs. 

A  shell  application  should  use  the  following  procedure  to  quit: 

1.  If  the  shell  application  has  requested  any  memory  buffers  it 
must  release  (dispose  of)  them. 

2.  The  shell  application  should  place  an  error  code  in  the 
accumulator.  If  no  error  occurred,  the  code  should  be  $0000 

a  °°e,$FFFF  Can  be  used  as  a  «eneraI  (nonspecific)  error 
code.  Other  error  codes  are  up  to  the  controlling  program  to 
define  and  handle. 

3.  The  shell  application  should  execute  an  RTL  or  if  the  shell 
supports  it,  a  ProDOS  16  QUIT  call. 


Desk  accessories 

A  desk  accessory  is  a  small  program  that  a  user  can  run  without 
closing  down  an  already-running  application.  The  Apple  IIGS 
supports  two  different  kinds  of  desk  accessories: 
■  Classic  desk  accessories  (CDA'S)  are  designed  to  execute  in  a 

non-desktop  environment.  The  CDA  interrupts  the  application 

and  gets  full  control  of  the  computer. 
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For  full  details  on  the  Desk 
Manager  and  its  desk  accessory 
suppport,  see  "Desk  Manager"  in 
the  Apple  IIGS  Toolbox 
Reference 


■  New  desk  accessories  (NDA'S),  on  the  other  hand,  are  designed 
to  execute  in  a  desktop  environment.  As  such,  they  operate  in  a 
window  and  are  subject  to  the  same  rules  as  an  event-driven 
application.  They  are  not  stand-alone  applications,  however, 
because  they  rely  upon  another  application  to  start  up  the 
Apple  IIGS  tools. 

Neither  type  of  desk  accessory  has  a  lot  of  extra  programming 
overhead  apart  from  the  actual  task  the  accessory  performs.  Both 
types  depend  heavily  for  support  upon  the  Apple  IIGS  tool  set 
called  the  Desk  Manager. 


Writing  classic  desk  accessories 

A  classic  desk  accessory  must  start  with  a  header  consisting  of  a 
name  string,  a  pointer  to  the  start  of  the  code,  and  a  pointer  to 
the  shutdown  routine. 


StartofCDA 


str'Name  of  DA1 

dc  i4 'StartOfDACode' 

dc  14 ' ShutDownRoutine' 


DA  name  (this  is  an  APW  macro) 
Pointer  to  start  of  code 
Pointer  to  shutdown  routine 


When  a  CDA  gets  control  from  the  Desk  Manager,  the  processor 
is  in  full  native  mode.  Because  the  Desk  Manager  has  already 
saved  the  necessary  parts  of  the  old  environment,  the  CDA  can 
concern  itself  solely  with  its  own  work. 

A  CDA  follows  this  basic  procedure: 

1.  It  initializes  for  the  machine  environment  it  needs.  The  Desk 
Manager  has  already  saved  the  old  state  when  the  CDA  gets 
control. 

2.  It  does  the  actual  work  of  the  CDA.  Like  all  Apple  IIGS 
applications,  a  CDA  should  ask  the  Memory  Manager  for  any 
space  that  it  needs.  In  addition,  the  CDA  must  leave  the  stack  as 
it  was  when  the  CDA  got  control. 

3.  It  returns  to  the  Desk  Manager  with  an  RTL.  The  Desk  Manager 
then  automatically  restores  the  old  state  and  returns  to  the  desk 
accessory  menu. 

Every  CDA  must  have  a  shutdown  routine.  The  shutdown  routine 
is  called  every  time  the  Desk  Manager  shuts  down. 

Classic  desk  accessories  have  the  ProDOS  file  type  $B9.  On  disk, 
they  must  be  in  the  DESK .  ACCS/  subdirectory  of  the  SYSTEM/ 
directory. 
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Writing  new  desk  accessories 

All  new  desk  accessories  are  loaded  from  the  disk  at  boot  time. 
When  an  NDA  gets  control  from  the  Desk  Manager,  the  processor 
is  in  full  native  mode.  By  convention,  the  NDA  can  assume  that 
the  tool  sets  shown  in  Table  8-1  have  already  been  loaded  and 
started  up.  If  the  NDA  needs  any  other  tool  sets,  it  must  load  and 
start  them  up  itself. 

Table  8-1 

Tool  sets  loaded  and  available  to  new  desk  accessories 


Tool  set 


Tool  Locator 
Memory  Manager 
Miscellaneous  Tool  Set 
QuickDraw  II 
Event  Manager 
Window  Manager 
Control  Manager 
Menu  Manager 
LineEdit  Tool  Set 
Dialog  Manager 
Scrap  Manager 


Note:  The  NDA  may  also  assume  that  the  Print  Manager  is  available, 
although  not  necessarily  loaded  and  started  up 

A  new  desk  accessory  has  a  structure  fundamentally  different  from 
that  of  a  desktop  application.  For  one  thing,  it  has  no  event 
loop— it  relies  on  the  application's  event  loop  and  the  Desk 
Manager  to  open  it,  prod  it  into  action,  and  close  it.  For  another, 
it  has  only  four  nonprivate  routines:  init,  open,  action,  and  close: 
□  The  Desk  Manager  calls  the  init  routine  to  initialize  the  NDA 
when  the  Desk  Manager  starts  up,  and  again  when  it  shuts  down. 
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□  The  Desk  Manager  calls  the  open  routine  when  the  NDA  is 
selected  by  the  user  from  the  Apple  menu.  The  open  routine 
opens  the  desk  accessory  window  and  returns  a  pointer  to  it. 

p  The  Desk  Manager  calls  the  action  routine  in  response  to  an 
event  within  the  NDA  window,  or  when  a  specified  time  period 
has  passed,  or  if  a  selection  has  been  made  from  an  NDA 
menu  or  the  Edit  menu,  and  in  other  special  cases.  The  action 
routine  performs  whatever  tasks  the  NDA  was  designed  for.  An 
action  code  passed  in  the  accumulator  tells  the  NDA  why  it  was 
called. 

p  The  Desk  Manager  calls  the  close  routine  to  close  the  desk 
accessory  window. 

The  processor  is  in  full  native  mode  on  entry  into  all  four 
routines.  All  four  routines  should  end  with  an  RTL  instruction. 

An  NDA  action  routine  follows  this  basic  procedure: 

1.  It  saves  important  global  values,  such  as  the  application's 
current  GrafPort. 

2.  Based  upon  the  action  code  received,  it  takes  appropriate 
action. 

3.  It  restores  the  global  values  and  returns  to  the  Desk  Manager 
with  an  RTL. 

You  must  start  the  NDA  with  an  identification  section  that 
specifies  the  pointers  to  the  four  routines,  the  NDA's  period  (how 
often  it  runs),  its  event  mask  (what  events  it  wants),  and  its  menu 
line  (text  defining  its  title  on  the  Apple  menu).  For  example,  the 
identification  section  could  look  like  this: 


StartofNDA 


dc  i4 'PtrToOpen' 
dc  i4 'PtrToClose' 
dc  i4 'PtrToAction' 
dc  i4 'PtrToInit ■ 
dc  i2  '  Period1 
dc  i2 'EventMask1 
dc  c'  MenuLine\H** ' 
dc  il'O' 


Pointer  to  open  routine 
Pointer  to  close  routine 
Pointer  to  action  routine 
Pointer  to  init  routine 
How  often  to  run 
What  events  to  retrieve 
Text  for  menu  item 
Terminator  for  the  menu  line 


New  desk  accessories  have  the  ProDOS  file  type  $B8.  On  disk,  they 
must  be  in  the  DESK.  ACCS/  subdirectory  of  the  SYSTEM/ 
directory. 
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Initialization  files 

Initialization  files  are  files  of  types  $B6  and  $B7,  in  the 
SYSTEM.  SETUP  subdirectory.  They  are  special-purpose  programs 
that  perform  initialization  at  system  startup,  before  any 
applications  have  been  launched. 

There  are  two  types  of  initialization  files — temporary  and 
permanent: 

■  Temporary  initialization  files  (type  $B7)  are  loaded  and 
executed  just  like  applications  ($B3),  except  that  they  must 
terminate  with  an  RTL  rather  than  a  QUIT.  They  are  removed 
from  memory  when  finished. 

■  Permanent  initialization  files  (type  $B6)  are  loaded  and 
executed  just  like  applications  ($B3),  except  for  these 
conditions: 

a  They  must  not  be  in  special  memory. 

a  They  cannot  permanently  allocate  any  direct-page/stack 
space. 

□  They  must  terminate  with  an  RTL  rather  than  a  QUIT. 

Permanent  initialization  files  are  not  removed  from  memory 
when  finished. 

With  initialization  files,  you  can  customize  the  operating 
environment  before  any  applications  are  loaded.  The 
TOOL .  SETUP  file  is  an  example  of  an  initialization  file;  it  loads 
RAM  patches  to  tool  sets.  TOOL .  SETUP  is  a  permanent 
initialization  file  because  other  system  software  needs  it  during 
program  execution.  If  your  initialization  files  need  to  execute  only 
once,  make  them  temporary. 

♦  Note.-  Don't  confuse  these  initialization  files  (programs 
executed  at  system  startup)  with  initialization  segments  (pieces 
of  an  application  executed  when  the  application  starts  up).  See 
"Loading  Programs  and  Segments"  in  Chapter  6. 
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l  interrupt  is  a  signal  to  a 
omputer  that  stops  the 
ixecution  of  an  ongoing 
jfogram  while  a  higher-priority 
program  Is  executed.  It  Is  usually 
an  external,  hardware-generated 
gnal,  but  software  Interrupts  are 
ossible  as  well. 


Interrupt  handlers 

On  the  Apple  IIGS,  interrupts  may  be  handled  at  either  the 
firmware  or  the  software  level.  The  built-in  interrupt  handers  are 
in  firmware  (discussed  in  the  Apple  IIGS  Firmware  Reference); 
user-installed  interrupt  handlers  are  software  and  may  be  called 
directly  by  the  firmware  or  through  ProDOS  16. 

When  the  Interrupt  Request  (IRQ)  line  on  the  Apple  IIGS 
microprocessor  is  activated,  or  when  a  software  interrupt  occurs, 
the  microprocessor  stops  executing  the  current  application  and 
transfers  control  to  the  firmware  interrupt-processing  routines. 
The  built-in  interrupt  handler  processes  the  interrupt  if  the 
application  has  not  provided  its  own  interrupt  handler. 


The  built-in  interrupt  handler 

The  Apple  IIGS  built-in  interrupt  handler  is  a  firmware  program  that 
performs  a  sequence  of  steps  to  handle  system  interrupts.  When  a 
program  is  interrupted,  the  handler  saves  the  current  state  of  the 
system.  The  handler  then  processes  the  interrupt  itself  or  passes 
execution  to  another  handler,  either  internal  or  external.  On  com- 
pletion of  interrupt  processing,  the  interrupted  program  regains 
control  and  can  continue  as  though  nothing  had  happened. 

Figure  8-2  and  the  following  explanation  give  a  simplified  picture 
of  the  steps  taken  by  the  built-in  interrupt  handler;  they  emphasize 
the  course  of  execution  when  the  interrupt  is  to  be  serviced  by  a 
user-installed  handler. 

1.  When  an  interrupt  signal  occurs,  execution  jumps  indirectly 
through  the  interrupt  vector  EIRQ  if  running  in  emulation 
mode  when  the  interrupt  occurred,  or  NIRQ  if  in  native  mode. 

2.  The  system  then  tests  to  see  whether  the  interrupt  was  the  result 
of  a  software  Break  instruction.  If  it  was,  the  system  vectors  to  a 
break  handler  through  a  break  handler  vector  in  bank  $E1.  If 
no  break  handler  is  installed,  execution  passes  through  the  user 
break  vector  at  $3F0  in  bank  zero,  which  normally  points  to  the 
Monitor  program. 
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3.  If  the  interrupt  source  was  not  a  Break  instruction,  the  interrup 
handler  saves  the  absolute  minimum  amount  of  information 
about  the  machine  state — just  that  necessary  to  read  an 
incoming  serial  character — and  then  tests  for  AppleTalk  and 
serial  port  interrupts.  This  hasty  action  is  necessary  so  that 
incoming  characters  in  high-speed  transmission  will  not  be 
lost.  If  the  interrupt  is  a  serial  interrupt,  the  firmware  executes  i 
JSL  instruction  to  the  serial  port  handler. 

4.  If  the  interrupt  is  not  a  serial  interrupt,  the  interrupt  handler 
saves  the  rest  of  the  machine  state  and  establishes  a  specific 
interrupt  memory  configuration,  as  described  next  under  "En- 1 
vironment  Handling  for  Interrupt  Processing."  It  begins  a  polli 
loop,  testing  each  of  the  possible  interrupt  sources  in  turn. 

5.  If  no  internal  interrupt  handler  claims  the  interrupt,  then  (andj 
only  then)  the  firmware  jumps  through  the  user  interrupt 
vector,  to  a  user-installed  routine  that  handles  the  interrupt. 
The  address  of  the  user  interrupt  routine  is  found  in  bank  $00, 
addresses  $3FE  Gow  byte)  and  $3FF  (high  byte). 


65C816 

interrupt 

vectors 

(Bank  $FF) 


EIRQ 
NIRQ 
etc. 


Switch  to  high  speed 


JSL  AppleTalk 
JSL  Seriallnt 


($3F0) 
Bank  $00 


Save  more  state  info, 
poll  all  other  sources 


-►JSL 
-►JSL 
-►JSL 


If  none  claims  it 


(Usually  the  monitor) 


User  interrupt  vector 
<$3FE)  in  Bank  $00 


Figure  8-2 

Built-in  interrupt  handler  (simplified) 


Chapter  8:  What  Type  of  Program  to  Write? 


Environment  handling  for  interrupt  processing 

For  each  type  of  interrupt,  the  processor  can  be  in  either 
emulation  or  native  mode.  The  built-in  interrupt  handler  must 
save  the  current  environment  in  each  case,  set  the  interrupt 
environment,  process  the  interrupt  through  the  appropriate 
interrupt  handler,  and  then  restore  the  original  environment 
before  returning  control  to  the  interrupted  program. 

The  interrupt  environment  is  the  machine  state  that  your  inter- 
rupt handler  finds  when  it  gains  control.  If  your  handler  is  called 
from  the  user  interrupt  vector,  the  environment  includes  these 
conditions: 

□  emulation  mode 

D  slow  speed  (1MHz) 

D  text  page  1  switched  in  (main  screen  holes  available) 

□  main  memory  switched  in  (for  reading  and  writing) 
D  $D000-$FFFF  ROM  mapped  into  bank  $00 

□  main  stack  and  zero  page  switched  in 

D  main  stack  pointer  active  (auxiliary  stack  pointer  saved) 

If  your  handler  is  called  through  a  JSL  from  the  built-in  handler 
before  jumping  to  the  user  interrupt  vector,  the  same  state  applies 
except  that  the  machine  is  in  8-bit  native  mode  and  running  at 
fast  speed. 

♦  ProDOS  16:  If  your  interrupt  handler  is  installed  through 
PRoDOS  16,  the  machine  state  it  finds  is  somewhat  different. 
See  "Interrupt  Handling  Under  ProDOS  16,"  later  in  this 
section. 

After  the  interrupt  has  been  processed,  the  system  interrupt 
handler  restores  the  environment  and  registers  to  their 
preinterrupt  state  and  executes  an  RTI  (return  from  interrupt), 
returning  to  the  executing  program. 
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Descriptions  and  locations  of  all 
interrupt  vectors  are  listed  in 
Appendix  D  of  Apple  Hgs 
Firmware  Reference, 


Interrupt  soft  switches  are 
documented  under  "Soft 
Switches"  In  the  Apple  Hgs 
Firmware  Reference. 


Writing  and  installing  your  own  interrupt  handler  I 

Lll  J  Y  modlfy'n8  the  interrupt  vector  locations  such 

as  the  user  interrupt  vector  at  $00  03FE.  However  you  mus  'be 

he^:^;11  °f  thC  CTemi0nS  S^Cified  ^  Chap't     S5  f 
the  Apple  IIGS  Firmware  Reference  regarding  interrupt 

^S^uTT  SUfe  t0  reSt°re  ^  <™™P~rnen 
sys em in  Cn  7      °n  6Ty  t0  y°Ur  handler-  ™s  all°ws  the 
system  in  turn  to  restore  the  environment  to  its  original  state 

If  you  write  a  handler  to  be  called  from  the  $3FE  interrupt  vect 
it  must  do  the  following  tasks:  interrupt  vi 

1.  Verify  that  the  interrupt  came  from  the  expected  source 

2.  Handle  the  interrupt  appropriately. 

3.  Clear  the  appropriate  interrupt  soft  switch. 

4.  Restore  everything  to  the  state  it  was  in  when  the  interrupt 

'  fnSo?6  bUi,t"in  imerrUpt  handlef  ^  routing  an  m 

D  bemuse  the  tT^  T™™  TGSp0nSe  time  for  ~P* 

°  l™llTnTde  'lTmptS  arS  SUpP°rted  in  ba<*  $00  only 
memo"  S^  T"^  ™  ^^  -erywhere  n 

D  S.r?  Wm  ^  8reatef  if  y°Ur  intefruP^  ^ndler  j 
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Interrupt  handling  under  ProDOS  16 

You  can  write  an  interrupt  handler  and  install  it  under  ProDOS 
16,  if  you  wish.  ProDOS  16  installs  its  own  vector  at  location  $00 
03FE  (page  3  in  bank  zero),  so  when  an  interrupt  occurs,  execution 
passes  through  that  location.  At  that  point  the  microprocessor  is 
running  in  emulation  mode,  using  the  standard  clock  speed  and  8- 
bit  registers.  The  vector  at  $00  03FE  points  to  another  bank  zero 
location,  that  in  turn  passes  control  to  the  ProDOS  16  interrupt 
dispatcher.  The  interrupt  dispatcher  switches  the  processor  to  full 
native  mode  (including  higher  clock  speed)  and  then  polls  the 
user-installed  interrupt  handlers.  When  the  interrupt  has  been 
serviced,  ProDOS  16  returns  to  emulation  mode  and  passes 
control  back  to  the  built-in  interrupt  handler. 

Figure  8-3  is  a  simplified  picture  of  what  happens  when  a  device 
generates  an  interrupt  that  is  handled  through  a  ProDOS  16 
interrupt  handler. 


From  built-in 
interrupt  handler 


User  interrupt  vector 
($3FE)  in  Bank  $00 


JMP 


ProDOS  16  Interrupt 
Dispatcher 


RTL  back  to  ProDOS  16 

Interrupt  Dispatcher 

(then  RTI  back  to 

built-in  interrupt  handler) 


Switch  to 
full  native 
mode 


Poll  each  handler 

in  seauence: 

will  one  accept 

the  interrupt? 


JSL 


User-installed 
handler 


If  none  claims  it 


Unclaimed  interrupt 
(fatal  error) 

Figure  8-3 

Interrupt  handling  through  ProDOS  16 
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ProDOS  16  supports  up  to  1 6  user-installed  interrupt  handlers. 
When  an  interrupt  occurs  that  is  not  handled  by  firmware, 
ProDOS  16  transfers  control  to  each  handler  successively  until 
one  of  them  claims  it.  There  is  no  grouping  of  interrupts  into 
classes;  their  priority  rankings  are  reflected  only  by  the  order  in 
which  they  are  polled. 

If  you  write  an  interrupt  handler  to  run  under  ProDOS  16,  note 
these  conventions: 

□  Your  handler  will  gain  control  with  the  machine  in  full  native 
mode  (e,  m,  and  x  =  0),  with  a  fast  clock  speed. 

□  Interrupts  will  be  disabled.  Do  not  re-enable  interrupts  from 
within  your  interrupt  handler. 

□  The  handler  must  exit  with  an  RTL  instruction.  The  machine 
should  again  be  in  full  native  mode,  at  fast  speed.  The  carry 
flag  must  be  cleared  (  =  0)  if  the  interrupt  was  serviced,  and  set 
C  =  1)  if  it  was  not— that  is  how  ProDOS  16  knows  whether  or 
not  your  handler  has  claimed  the  interrupt. 

To  make  your  interrupt  handler  active,  install  it  with  the  ProDOS 
16  ALLOCJNTERRUPT  call.  To  remove  it,  use  the  DEALLOC_ 
INTERRUPT  call.  Be  sure  to  enable  the  hardware  generating  the 
interrupt  only  after  the  routine  to  handle  it  is  allocated;  likewise, 
disable  the  hardware  before  the  routine  is  deallocated. 


User  tool  sets 

The  Apple  IIGS  Toolbox  is  quite  extensive  and  provides  a  great 
deal  of  programming  convenience;  there  are  over  800  separate 
routines  that  you  can  call  from  your  applications.  Furthermore, 
because  of  the  flexibility  of  the  Tool  Locator  system,  your 
application  is  not  restricted  to  even  this  large  number  of  tool 
calls.  In  addition  to  the  system  tools  (provided  by  Apple),  you 
can  write  and  install  your  own  tool  sets,  called  user  took. 

Writing  and  installing  user  tool  sets  is  fully  documented  under 
"Writing  Your  Own  Tool  Set"  in  the  Apple  IIGS  Toolbox 
Reference.  We  won't  repeat  that  information  here,  beyond  listing 
these  few  main  points: 


Chapter  8:  What  Type  of  Program  to  Write? 


□  The  open-ended,  flexible  nature  of  the  Tool  Locator  is  what 
makes  it  possible  to  add  your  own  tool  sets.  The  Tool  Locator 
requires  no  fixed  ROM  location  and  few  fixed  RAM  locations, 
so  it  may  easily  modify  its  data  structures  to  incorporate  new 
tool  sets. 

d  Each  tool  set  is  assigned  a  permanent  tool  number.  System 
tools  are  assigned  numbers  by  Apple;  you  can  assign  your  own 
numbers  to  user  tool  sets  that  you  create.  Assignment  starts  at  1 
and  continues  as  successive  integers  (2,  3,  4,  and  so  forth). 
Table  8-2  lists  the  presently  defined  system  tool  numbers. 


Table  8-2 

Tool  set  numbers 

Hexadecimal 

Decimal 

Name 

$01 

1 

Tool  Locator 

$02 

2 

Memory  Manager 

$03 

3 

Miscellaneous  Tool  Set 

$04 

4 

QuickDraw  II 

$05 

5 

Desk  Manager 

$06 

6 

Event  Manager 

$07 

7 

Scheduler 

$08 

8 

Sound  Tool  Set 

$09 

9 

Apple  Desktop  Bus  Tool  Set 

$0A 

10 

SANE 

$0B 

11 

Integer  Math  Tool  Set 

$0C 

12 

Text  Tool  Set 

$0E 

14 

Window  Manager 

$0F 

15 

Menu  Manager 

$10 

16 

Control  Manager 

$11 

17 

System  Loader 

$12 

18 

QuickDraw  II  Auxiliary 

$13 

19 

Print  Manager 

$14 

20 

LineEdit  Tool  Set 

$15 

21 

Dialog  Manager 

$16 

22 

Scrap  Manager 

$17 

23 

Standard  File  Operations 

$19 

25 

Note  Synthesizer 

$1A 

26 

Note  Sequencer 

$1B 

27 

Font  Manager 

$1C 

28 

List  Manager 

User  tool  sets 
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□  Each  routine  within  a  tool  set  is  assigned  a  permanent! 
function  number.  Function  numbers  start  at  1  in  each  tool  set 
and  continue  as  successive  integers.  Certain  standard  calls  m 
be  present  in  every  tool  set,  and  so  certain  function  numbers 
are  reserved.  Table  8-3  lists  them.  See  the  toolbox  manual  for 
explanations  of  what  each  function  must  do. 

□  There  are  some  general  rules  and  design  considerations  that 
tool  sets  must  follow.  For  example,  tool  sets  receive  control  in 
full  native  mode;  they  must  obtain  any  needed  work  space  from 
the  Memory  Manager;  they  must  provide  some  sort  of  interrupt 
environment;  and  they  must  restore  the  caller's  operating 
environment  before  returning  control  to  the  caller.  See  the 
Apple  IIGS  Toolbox  Reference  for  details  on  these  and« 
design  requirements. 

Table  8-3 

Standard  tool  set  routine  numbers 


FuncNum  Description 


1 
2 
3 
4 
5 
6 
7 
8 


Boot  initialization 

Application  startup 

Application  shutdown 

Version  information 

Reset 

Status 

Reserved  for  future  use 

Reserved  for  future  use 
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This  is  as  far  as  we  can  take  you  in  this  book.  For  your  next  step, 
spread  out  your  development-environment  manuals,  Apple  IIGS 
technical  manuals,  and  the  Apple  IIGS  ToolBox  Reference,  arj§ 
play  with  HodgePodge  on  the  Apple  IIGS  or  start  your  own 
applicaton.  In  parting,  we'll  give  you  a  few  hints — mostly 
summaries  of  the  ideas  presented  throughout  the  book— and  M 
mention  two  organizations  that  can  help  you  become  a  successful 
Apple  IIGS  developer. 


Modify  HodgePodge 

The  easiest  way  to  get  started  on  your  own  desktop  application 
may  be  to  take  HodgePodge  and  modify  it  incrementally. 
Recompile  it  and  run  it  after  each  small  change  to  see  how  yofl 
changes  look  (or  even  if  they  work). 

You  might  begin  by  modifying  text  within  dialog  boxes,  or 
changing  the  names  of  menu  titles  or  items.  As  you  become  a 
little  braver,  try  adding  (or  removing)  menus  or  menu  items,  m 
adding  (or  removing)  the  subroutines  called  from  those  menu 
items.  Remember  that  adding  an  item  to  a  menu  will  require  1 
changing  the  routine  DoMenu  as  well  as  changing  the  menu 
definitions  themselves — not  to  mention  writing  a  subroutine  tfl 
does  something  when  the  menu  item  is  selected. 

Soon  you'll  become  more  ambitious,  and  you  can  branch  in  i 
almost  any  direction.  Add  a  routine  that  plays  a  song  when  called. 
Define  a  new  window  type,  perhaps  even  one  that  permits  the  user 
to  draw  or  type  into  it.  Define  a  file  type  for  that  window  type,  and 
allow  the  user  to  save  results  to  disk.  Give  HodgePodge  the  ability 
to  cut  and  paste  to  and  from  the  Clipboard,  and  display  the  \ 
Clipboard  window.  Play  with  menu-  and  window-frame  colors. 

Your  imagination  is  your  only  real  constraint.  Have  fun  and  ] 
challenge  your  limits;  the  Apple  IIGS  is  a  willing  partner  in  thifl 
adventure. 
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Design  your  program  carefully 

We've  discussed  design  considerations  for  Apple  IIGS  desktop 
applications  throughout  the  book,  but  some  in  particular  are 
worth  repeating.  As  you  work  on  your  own  programs,  either  by 
modifying  HodgePodge  or  starting  from  scratch,  keep  these 
points  in  mind: 

■  Follow  the  Human  Interface  Guidelines:  Follow  the  underlying 
concepts,  as  well  as  the  surface  implementation,  of  the 
guidelines.  They  describe  a  tested  and  proven  interface, 
familiar  and  friendly  to  millions  of  users.  If  you  go  beyond  the 
guidelines,  make  it  a  natural  extension. 

■  Design  data  structures  before  writing  code  Your  menus, 
windows,  controls,  dialog  boxes,  and  alerts  influence  program 
structure  so  strongly  that  they  should  be  carefully  planned  and 
defined  at  the  beginning.  You'll  save  yourself  wasteful  rewriting 
and  awkward  patching  if  your  code  organization  flows  naturally 
from  the  design  of  your  data  structures. 

■  Test  for  errors:  Make  it  a  habit  to  put  error-testing  code  after 
toolbox  calls.  It  can  help  inform  the  user  and  can  keep  your  pro- 
gram from  doing  harmful  things  to  the  user's  system  or  data. 

■  Save  and  restore:  When  a  subroutine  accesses  the  desktop,  it 
may  not  always  know  the  exact  state  of  things.  Note  that  many 
HodgePodge  routines  start  with  a  GetPort  call  to  save  the 
current  state  of  the  desktop,  and  end  by  restoring  the  desktop 
(with  a  SetPort  call).  It's  another  good  habit  to  get  into. 

■  Lock  handles  while  in  use:  If  your  program  has  allocated  a 
piece  of  memory  accessed  by  a  handle,  be  sure  to  lock  it  just 
before  using  it.  A  lot  of  memory  errors  are  caused  by  trying  to 
access  data  that  has  been  moved. 

■  Unlock  handles  when  not  in  use:  Don't  prevent  the  Memory 
Manager  from  doing  its  job. 

■  Dispose  handles  when  finished:  Don't  prevent  the  Memory 
Manager  from  doing  its  job. 

■  Make  it  easy  to  translate:  If  you  want  to  appeal  to  international 
markets,  remember  to  place  in  one  or  more  individual  data 
areas  all  text  that  is  to  be  displayed,  so  that  it  may  be  found 
and  modified  easily. 

■  Design  for  "Undo":  Consider  including  a  facility  that  allows  the 
user  to  reverse  his  actions  to  undo  a  mistake.  Your  customers 
will  be  eternally  grateful. 
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Join  APDA 

If  you  are  already  a  member  of  the  Apple  Programmer's  and 
Developer's  Association  (APDA),  you  know  that  it  is  the  fastest 
way  to  get  the  most  recent  software,  documentation,  and  other 
information  of  interest  to  developers.  If  you  are  not  a  member, 
it  s  easy  to  join. 

APDA  is  a  membership  organization  for  both  professional  and 
advanced  amateur  programmers  and  developers.  It  was  founded 
by  Apple  Computer  and  the  A.P.P.L.E.  Co-op  near  Seattle, 
Washington;  its  purpose  is  to  publicize  and  distribute 
programming  tools  and  technical  documentation  for  Apple 
computers. 

APDA  serves  as  a  "one-stop  shopping  center."  It  offers  both 
linished  products  from  Apple  and  other  vendors,  and  prerelease 
versions  of  many  Apple  development  tools  and  documents.  Some 
small-volume  products,  not  suitable  for  the  retail  market  are 
available  only  through  APDA.  Other  products,  scheduled  for  the 
retad  market,  are  offered  through  APDA  in  prerelease  versions,  on 
an   as-is"  (no  support)  basis. 

If  you  join  APDA,  you  will  receive  quarterly  catalogs  (and  more 
frequent  updates)  of  the  available  material  for  both  Apple  II  and 
Macintosh  development.  Membership  is  open  to  all  interested 
parties.  Yearly  dues  are  $20.00. 

Write  to 

Apple  Programmer's  and  Developer's  Association 
290  SW  43rd  Street 
Renton,  WA  98055 

(206)  251-6548 


Become  an  Apple  Developer 

If  you  are  a  developer  with  a  product  soon  to  reach  the 
commercial  market,  you  may  want  to  become  an  Apple  Certified 
Developer.  As  a  Certified  Developer,  you  will  receive  monthly 
mailings  including  a  newsletter,  Apple  II  and  Macintosh  Technical 
Notes,  pertinent  Developer  Program  information,  and  all  the 
ktest  news  relating  to  Apple  products.  You  will  have  access  to  our 
Developer  Hotline  for  general  developer  information 
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Once  you  are  certified,  Apple's  Developer  Technical  Support  staff 
can  provide  technical  assistance  during  your  product's  evolution. 
Our  Technical  Support  engineers  will  answer  your  development 
questions  within  24  hours  by  electonic  mail. 

The  Certified  Developer  program  is  for  professional  hardware 
and  software  developers  who  plan  to  have  a  finished  commercial 
product  within  18  months.  If  you  fit  this  description  and  are 
interested,  please  write  for  an  application.  You  will  need  to  submit 
information  on  previous  products  and  your  present  business  plan 
along  with  your  completed  application. 

Write  to 

Developer  Programs 

Apple  Computer,  Inc. 

20525  Mariani  Avenue,  M.S.  27W 

Cupertino,  California   95014 

(408)  973-4897 


Licensing  Apple  software 

If  the  software  you  write  uses  all  or  part  of  some  Apple  software 
(such  as  ProDOS  16  or  the  Apple  IIGS  Toolbox),  you  will  need  to 
license  the  use  of  that  software  from  Apple  Computer.  You 
needn't  license  any  parts  of  HodgePodge  you  use,  but  you  will 
need  to  license  any  system  software  that  accompanies  or  is 
incorporated  into  your  application. 

A  modest  yearly  fee  authorizes  you  to  use  Apple  software  in  your 
product.  There  are  no  royalties.  Please  contact 

Software  Licensing 

Apple  Computer,  Inc. 

20525  Mariani  Avenue,  M.S.  28B 

Cupertino,  CA  95014 

Attn:  Software  Licensing  Program 

(408)  973-4667 
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Appendix  A 


Converting   Macintosh      1 
Programs  to  the  Apple  IIgs 


If  you  have  written  a  desktop  application  for  the  Macintosh,  tf 
may  be  able  to  convert  it  to  run  on  the  Apple  IIGS  without 
completely  rewriting  it.  On  a  conceptual  level,  the  task  should  be 
rather  simple— after  all,  program  organization  and  toolbox 
capabilities  are  similar  for  both  computers.  But  when  it  comes  to 
implementation,  there  are  many  differences  that  require  careful 
attention  to  details  of  coding.  This  appendix  notes  some  of  the 
details  to  keep  in  mind  when  converting  Macintosh  programs  to 
the  Apple  IIGS. 


High-level  languages 


Programming  in  a  high-level  language  can  insulate  you  from 
many  of  the  differences  among  machines.  However,  the 
individual  toolbox  calls  are  different  enough  between  the 
Macintosh  and  the  Apple  IIGS  that  in  most  cases  it  will  not  be 
possible  just  to  recompile  Macintosh  code  and  expect  it  to 
the  Apple  IIGS. 
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The  best  approach  is  probably  to  regard  the  conversion  process 
algorithmically,  rather  than  literally.  In  other  words,  don't  expect 
that  you  will  be  able  to  drop  a  whole  program  or  even  any  one 
routine,  unchanged,  into  an  Apple  IIGS  program.  Use  your 
Macintosh  program's  organization  as  a  framework  into  which  to 
place  individually  converted  routines.  Even  though  most  of  the 
organization  and  much  of  the  original  code  can  be  translated 
exactly,  you'll  have  to  locate  those  statements,  calls,  and  structures 
that  are  incompatible  with  the  Apple  IIGS  environment. 

This  doesn't  necessarily  mean  pouring  over  the  source  code  line- 
by-line.  In  general,  you  might  be  able  to  port  well-behaved  high- 
level  code,  just  by  carefully  locating  and  modifying  tool  calls  and 
any  code  that  accesses  toolbox  data  structures. 

Of  course,  if  you  have  a  routine  that  makes  no  tool  calls,  accesses 
no  tool  structures,  and  otherwise  makes  no  Macintosh-specific 
assumptions,  you  may  indeed  be  able  to  convert  it  simply  by 
recompiling  it. 


Assembly  language 

Approaching  the  conversion  process  algorithmically  rather  than 
literally  is  even  more  critical  when  converting  programs  written  in 
assembly  language.  Besides  toolbox  differences,  you  are  faced 
with  fundamentally  different  microprocessor  architectures  and 
instruction  sets,  very  different  memory  maps,  and  a  host  of  other 
low-level  differences  between  the  two  types  of  computer.  The  only 
possible  aproach  is  to  think  of  your  Macintosh  program  as  an 
organizational  shell  in  which  every  routine  will  need  extensive 
revision  to  convert  correctly. 

Here  are  just  a  few  of  the  differences  to  keep  in  mind. 

■  Registers:  The  65816  does  not  have  nearly  the  number  of 
registers  that  the  68000  has,  so  you  will  have  to  store  more  of 
your  variables  in  memory — usually  local  memory  (direct  page). 

■  Direct  page:  Direct  page  is  an  Apple  IIGS  concept  that  can  be 
very  useful,  especially  if  you  are  constructing  tables  in  memory 
and  accessing  them  by  offsets.  If  your  Macintosh  program 
allocates  such  data  structures  on  the  heap,  you  can  gain 
efficiency  by  putting  them  onto  the  Apple  IIGS  direct  page. 
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Stack:  Your  stack  on  the  Apple  IIGS  is  likely  to  be  smaller  than 
what  you  are  used  to  on  the  Macintosh.  More  of  your  variables 
and  data  structures  will  be  allocated  in  other  parts  of  memory. 

Memory  space  and  segmentation:  Your  program  may  have  to 
run  in  less  space  on  an  Apple  IIGS  than  it  may  be  used  to  on  a 
Macintosh.  Therefore,  segmentation  can  be  very  important. 
Break  the  program  into  segments,  and  use  as  many  dynamic 
segments  as  possible. 

Video  display:  The  Apple  IIGS  offers  you  two  different  Super 
Hi-Res  graphics  modes — 320  and  640  pixels  across.  Both  use 
color,  but  neither  has  square  pixels. 


Toolbox  differences 

If  you  compare  the  Macintosh  and  Apple  IIGS  toolboxes,  you'll 
see  that  many  routines  have  identical  names  and  function  in  the 
same  way.  Many  others  do  not,  however,  so  watch  out  for 
differences  when  using  the  tools.  In  particular,  the  required 
parameters  and  the  order  of  the  parameters  may  differ  between 
the  Macintosh  and  Apple  IIGS  versions  of  a  particular  call.  Be  1 
sure  to  look  up  each  routine  in  the  Apple  IIGS  Toolbox  Reference 
before  using  it. 

Some  groups  of  tool  calls  are  more  alike  than  others.  For 
example,  many  QuickDraw  calls  are  identical  or  very  similar  in 
both  environments.  Thus,  graphic  routines  might  be  relatively 
simple  to  translate.  On  the  other  hand,  calls  that  directly  access 
or  manipulate  memory,  such  as  Memory  Manager  calls  and 
handle  manipulations,  can  operate  very  differently  in  the  two 
environments — even  when  they  look  the  same.  Be  careful. 

Also  keep  in  mind  that  the  records  that  describe  toolbox 
structures  such  as  GrafPorts  and  controls  are  different.  Fields  that 
exist  in  one  environment  may  not  be  in  the  other.  So  be 
particularly  careful  if  you  access  data  structures  directly. 

Some  specific  recommendations  on  how  to  handle  toolbox 
differences  follow. 
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Pascal  HodgePodge  Is  listed  In 
Appendix  G.  Furthermore, 
ndividual  routines  are  listed  and 
described  throughout  the  book. 
See  Table  2-1. 


Resources 

To  a  Macintosh  programmer,  the  term  resource  means  something 
much  more  specific  than  a  useful  item.  Resources  are  certain 
types  of  data  structures,  easily  accessible  by  the  programmer,  that 
help  to  separate  code  from  static  data  and  make  program 
modification  simpler. 

The  Apple  HGS  has  no  predefined  structures  like  resources,  and  no 
Resource  Manager  or  resource  editors  for  manipulating  them.  So, 
in  conversion,  you  will  have  to  move  your  resources  from  the 
resource  fork  of  your  file  into  your  program  code,  either  as 
separate  data  segments  or  files,  or  merged  into  the  execution 
stream.  The  Pascal  version  of  the  sample  program  HodgePodge 
shows  several  ways  to  do  this: 

■  Icons:  You  can  define  your  icons  by  directly  creating  a  pattern 
in  memory,  as  HodgePodge  does  with  the  Apple  icon  in 
InitGlobals  (file  HP  .  PAS). 

■  Text  strings:  Instead  of  a  string  or  string  list  resource,  you  can 
define  your  strings  in  initialization  routines  (as  HodgePodge 
does  with  its  menu  strings),  or  in  the  individual  routines  in 
which  they  are  needed  (as  HodgePodge  does  with  prompt 
strings  in  the  Standard  File  dialog  boxes). 

Remember,  keeping  all  your  strings  easily  accessible  will  make 
the  program  more  convenient  to  translate  or  otherwise  modify. 

■  Window  and  dialog  box  templates:  The  templates  (DLOG, 
WIND,  ALRT,  and  DITL  resources  on  the  Macintosh)  used  to 
define  your  windows  and  dialog  boxes,  and  the  controls  and 
items  within  them,  must  be  defined  within  the  body  of  your 
Apple  IIGS  code. 

Each  time  it  opens  a  window,  HodgePodge  defines  and 
initializes  a  parameter  list  that  controls  the  window's 
appearance  (part  of  the  routine  DoTheOpen  in  WINDOW. PAS). 
When  it  creates  an  alert  box,  it  calls  a  routine 
(MakeATemplate  in  DIALOG. PAS)  that  defines  the 
characteristics  of  an  alert  box  and  two  items  within  it. 

Other  resources  in  your  Macintosh  program  will  need  to  be 
converted  similarly. 
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TaskMaster  or  GetNextEvent? 

The  Apple  IIGS  offers  at  least  one  very  useful  event-handling 
capability  not  yet  available  on  the  Macintosh:  TaskMaster. 
TaskMaster  automatically  handles  many  standard  events  for 
standard  types  of  windows— resizing,  dragging,  scrolling,  updating 
and  activating,  and  so  on. 

On  the  other  hand,  the  Apple  IIGS  also  supports  "normal"  event- 
handling  with  GetNextEvent,  just  as  on  the  Macintosh.  So  it  might 
seem  more  efficient  to  keep  that  same  GetNextEvent  organization 
when  converting  an  existing  Macintosh  program. 

Usually  it  is  not.  Unless  your  program  constructs  unconventional 
windows  or  handles  them  in  an  unusual  manner,  it  is  probably 
best  to  change  from  GetNextEvent  to  TaskMaster  when  making  the 
conversion.  Using  TaskMaster  may  allow  you  to  eliminate  entire 
routines  from  your  progam,  routines  that  would  otherwise  need 
individual  attention  to  convert  correctly. 

HodgePodge,  for  example,  has  no  update  routine,  no  activate 
routine,  no  scrolling  procedure,  no  window-dragging  or  -resizing 
routines,  and  yet  it  supports  windows  that  do  all  those  things.  It 
may  greatly  simplify  your  conversion  to  switch  to  TaskMaster. 


QuickDraw  II 

QuickDraw  II  on  the  Apple  IIGS  is  quite  similar  to  QuickDraw  on 
the  Macintosh,  apart  from  extensions  to  support  Apple  IIGS  color 
display.  However,  keep  the  following  in  mind: 

□  The  conceptual  drawing  space  for  QuickDraw  II  has  boundary 
coordinates  -16K,  -16K,  16K,  16K,  compared  to  -32K,-32K  and 
32K.32K  on  the  Macintosh. 

a  QuickDraw  II's  pixel  images  are  similar  to  Macintosh 

QuickDraw's  bit  images,  but  pixels  are  described  by  more  than 
one  bit  each.  Bit  images  such  as  icons  will  have  to  be 
converted  to  pixel  images,  with  either  two  or  four  bits  per  pixel. 
Icons  are  not  as  restricted  on  the  Apple  IIGS  as  they  are  on  the 
Macintosh.  Besides  having  color,  they  may  be  of  arbitrary 
height  and  width,  rather  than  32  pixels  (bits)  on  a  side. 
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You  won't  need  to  change  most  drawing  commands — your 
black-and-white  Macintosh  drawings  will  convert  directly  to 
white-and-black  drawings  on  the  Apple  IIGS  screen. 

There  will  be  some  change  in  aspect  ratio  of  images  and  drawn 
objects  in  transferring  to  the  Apple  IIGS  screen,  and  significant 
changes  in  overall  size — Super  Hi-Res  pixels  are  not  square  and 
are  significantly  larger  than  Macintosh  screen  pixels. 

Text  drawing  and  text  measurement  on  the  Apple  IIGS  are 
similar  to  their  treatment  on  the  Macintosh.  The  Apple  IIGS 
font  definition  is  similar  to  that  of  the  Macintosh,  and  a  simple 
conversion  algorithm  allows  the  IIGS  to  use  any  font  developed 
for  the  Macintosh.  Most  Macintosh  QuickDraw  text  calls  are 
duplicated  precisely  in  QuickDraw  II. 

Some  calls  have  been  added  to  handle  the  CSt ring  data  type 
(a  sequence  of  characters  terminated  by  a  0  byte). 

QuickDraw  II  does  not  scale  text — the  Font  Manager  does.  In 
general,  the  interaction  between  the  Apple  IIGS  Font  Manager 
and  QuickDraw  II  is  different  from  the  close  relationship 
between  the  Font  Manager  and  QuickDraw  on  the  Macintosh. 
Font  selection  on  the  Apple  IIGS  requires  a  little  more  care 
than  on  the  Macintosh. 


File  system  differences 

ProDOS  16  is  the  Apple  IIGS  operating  system  for  desktop 
applications.  There  are  ProDOS  16  calls  equivalent  to  most 
Macintosh  File  Manager  calls,  but  some  parameters  are  different 
or  are  used  differently.  If  your  Macintosh  application  makes  File 
Manager  calls,  they  will  have  to  be  translated  to  ProDOS  16  calls. 

On  the  other  hand,  if  your  program  is  written  in  a  high-level 
language  and  uses  only  that  language's  file  access  facilities,  you 
might  not  have  to  do  any  translating  at  all.  On  recompiling  under 
a  IIGS  development  environment,  your  file  calls  will  be  translated. 

As  noted  under  "Resources"  earlier  in  this  appendix,  files  do  not 
have  separate  resource  and  data  forks.  Data  stored  as  resources  in 
your  Macintosh  files  will  have  to  be  redefined  and  stored  as 
standard  ProDOS  16  files. 
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If  your  program  handles  all  its  file  access  through  Standard  File 
Operations,  it  will  not  have  to  manipulate  pathnames  explicitly. 
Just  as  on  the  Macintosh,  the  Standard  File  Operations  Tool  Set 
on  the  Apple  IIGS  takes  care  of  all  that.  But  if  you  do  access  files  1 
by  name,  please  note  these  differences  from  the  Macintosh  file 
system: 

□  Filenames  under  ProDOS  16  are  more  restricted  than  on  the 
Macintosh.  Only  the  characters  A-Z,  1-9,  and  the  period  (.)  are 
permitted,  and  the  maximum  length  is  15  characters. 

□  ProDOS  16  permits  you  to  define  up  to  9  prefixes,  for 
convenient  simultaneous  access  to  files  in  several  different 
subdirectories. 

□  ProDOS  16  uses  a  hierarchical  file  system,  in  which  files  are 
grouped  into  subdirectories  and  accessed  by  pathname.  The 
present  Macintosh  file  system  is  also  hierarchical,  but  if  you 
have  an  early  Macintosh  program  written  for  the  flat  file 
system,  you  may  have  to  modify  it  to  account  for  pathnames 
instead  of  just  filenames. 


Other  toolbox  differences 

As  you  get  involved  in  the  conversion  process,  you  will  of  course 
discover  many  other  differences,  some  subde  and  some  obvious, 
between  the  Macintosh  and  Apple  IIGS  toolboxes.  There  are  far 
too  many  to  list  in  this  appendix,  but  here  is  a  sample: 

■  Memory  Manager:  The  Apple  IIGS  Memory  Manager  is 
conceptually  very  similar  to  the  Macintosh  Memory  Manager. 
However,  because  of  the  65C816  microprocessor  and  the 
architecture  of  the  Apple  IIGS,  the  Apple  IIGS  Memory 
Manager's  calls  are  very  different,  and  its  internal  data 
structures  totally  different,  from  those  of  the  Macintosh.  Pay 
extra-close  attention  to  converting  Memory  Manager  calls  and 
manipulating  its  data  structures  such  as  pointers  and  handles. 

■  Window  Manager/Control  Manager:  Windows  and  controls  can 
be  handled  differently  in  several  ways,  largely  because  of  the 
Window  Manager  routine  TaskMaster.  The  Apple  IIGS  has 
window  types  that  include  scroll  bars  (frame  scroll  bars) 
manipulated  automatically  by  TaskMaster.  The  use  of  frame 
scroll  bars  greatly  simplifies  window  handling. 


Appendix  A:  Converting  Macintosh  Programs  to  the  Apple  IIgs 


Frame  scroll  bars:  If  you  use  TaskMaster  and  have  it  manipulate 
frame  scroll  bars,  remember  that  the  scroll  bars  are  part  of  the 
window  frame,  not  the  content  region.  That  is,  unlike  standard 
scroll  bars  on  a  Macintosh  window,  they  are  outside  the 
window's  port  rectangle.  That  may  affect  your  clipping  and 
drawing  commands. 

Desk  Accessories:  If  you  are  converting  a  Macintosh  desk 
accessory,  it  will  become  a  new  desk  accessory  on  the  Apple 
IIGS. 

Standard  File  Operations:  The  Disk  button  on  the  Apple  IIGS 
works  differently  from  the  Drive  button  on  the  Macintosh. 
When  a  user  clicks  the  Disk  button,  Standard  File  first  looks  at 
the  disk  in  the  same  drive  the  current  disk  is  in.  If  the  current 
disk  is  no  longer  in  that  drive,  the  disk  in  that  drive  becomes 
the  current  disk.  If  the  current  disk  is  still  there,  the  Disk  button 
moves  to  the  next  disk  in  the  ProDOS  chain.  The  Disk  button 
works  this  way  because  a  user  can  change  disks  without  the 
system's  knowledge. 

Printing:  On  the  Apple  IIGS,  the  Choose  Printer  function  is 
part  of  the  Print  Manager,  rather  than  part  of  the  Chooser  desk 
accessory  as  on  the  Macintosh.  To  support  printing,  you  will 
need  to  add  a  Choose  Printer  menu  item  to  the  File  menu,  and 
create  a  short  routine  to  handle  it. 
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Enhancing  Standard 
Apple  II  Programs 


If  you  have  written  a  ProDOS  8-based  program  for  a  standard 
Apple  II  computer  (64K  Apple  II  Plus,  Apple  lie,  or  Apple  lie),  you 
should  be  able  to  run  it  without  modification  on  the  Apple  IIGS. 
The  only  noticeable  difference  will  be  its  faster  execution  because 
of  the  greater  clock  speed  of  the  Apple  IIGS — and  even  that 
difference  can  be  eliminated  if  you  wish.  However,  the  program 
will  not  be  able  to  take  advantage  of  any  advanced  Apple  IIGS 
features  such  as  its  large  memory,  the  toolbox,  the  mouse-based 
interface,  and  the  new  graphics  and  sound  abilities. 


This  appendix  discusses  some  of  the  basic  alterations  you  can 
make  to  upgrade  a  ProDOS  8  application  for  various  execution 
modes  on  the  Apple  IIGS.  Depending  on  the  program's  size  and 
structure  and  the  new  features  you  wish  to  install,  those  changes 
may  range  from  minor  to  drastic. 

♦  High-level  languages:  This  discussion  is  primarily  about 
assembly-language  programs.  If  you  have  a  standard  Apple  II 
program  written  in  a  compiled  BASIC  or  other  high-level 
language,  converting  it  to  run  in  native  mode  on  the  Apple  IIGS 
may  require  nothing  more  than  recompiling  it  on  an 
equivalent  Apple  IIGS  development  system.  Accessing  the 
toolbox  may  then  be  as  easy  as  adding  the  calls  to  your 
original  source  code. 
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65816  assembly  language  is 
described  In  the  Apple  IIGS 
Programmer's  Workshop 
Assembler  Reference. 


Relocatable  code  and  the 
Memory  Manager  are  discussed 
in  Chapter  6. 


Conceptual  differences 

For  the  purpose  of  program  conversion,  there  are  perhaps  three 
main  areas  of  difference  between  traditional  Apple  II  computers 
and  the  Apple  IIGS: 

■  Hardware  execution  modes:  The  65C816  microprocessor 
executes  in  both  native  mode  and  6502  emulation  mode.  In 
fact,  there  are  at  least  three  modes  to  consider: 

□  Emulation  mode  (e  flag,  m  flag,  and  x  flag  set).  The 
processor  functions  like  a  6502. 

D  Native  mode  with  the  m  flag  and  x  flag  set.  The  processor 
has  all  65C816  features,  but  the  accumulator  and  index 
registers  remain  8  bits  wide. 

□  Full  native  mode  (e  flag,  m  flag,  and  x  flag  cleared).  All 
65C816  features  are  available,  and  the  accumulator  and 
index  registers  are  16  bits  wide. 

The  65816  microprocessor  adds  several  new  addressing  modes 
and  instructions  to  those  of  the  6502.  All  6502  and  65C02 
instructions  are  still  available,  but  the  new  larger  registers  and 
relocatable  stack  and  direct  page  add  flexibility  and  power  to 
the  system. 

■  Tool  sets:  The  toolbox  is  the  essence  of  what  makes  the  Apple 
IIGS  more  powerful  and  convenient  than  other  Apple  II 
computers.  To  write  the  kinds  of  programs  described  in  this 
book,  you  need  access  to  the  toolbox.  Tool  calls  can  be  made 
while  in  full  native  mode  only. 

The  Apple  IIGS  also  provides  a  sophisticated  loader  and  a 
software  memory  manager.  To  take  full  advantage  of  the 
system,  you  should  write  relocatable  code,  and  request  any 
memory  you  need  through  Memory  Manager  calls.  Otherwise 
your  program  will  be  incompatible  with  other  programs  in 
memory,  such  as  desk  accessories  and  memory-resident 
utilities. 

■  Operating  systems:  The  Apple  IIGS  comes  equipped  with  two 
operating  systems:  ProDOS  8  and  ProDOS  16.  Unaltered 
standard-Apple  II  applications  can  run  on  the  Apple  IIGS  only 
under  ProDOS  8.  They  cannot  access  tool  sets  or  ProDOS  16. 
They  can  make  ProDOS  8  calls  only  while  in  emulation  mode. 
The  ProDOS  8  global  page  is  supported,  but  again  only  in 
emulation  mode. 
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ProDOS  8  is  discussed  in  the 
ProDOS  8  Technical  Reference 
Manual, 
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Proarnms 


See  "Setting  Up  Direct- 
Page/Stack  Space",  in 
Chapter  6. 


Writing  a  hybrid  application  is  not  easy,  and  the  results  for 
toolbox  access  are  not  always  entirely  satisfactory.  You'll  need  to 
address  at  least  these  issues: 

■  Loading  RAM  patches:  If  your  program  is  self-booting  (starts  up 
directly  under  ProDOS  8)  on  the  Apple  IIGS,  ProDOS  16  and 
the  System  Loader  will  not  have  been  activated.  Therefore  RAM 
tool  sets  and  RAM  patches  to  die  ROM  tool  sets  will  not  be  in 
place.  There  are  several  possible  responses  to  this  problem: 

d  Do  without  the  patches  or  RAM-based  tools. 

□  Write  your  own  RAM-based  tool  set,  convert  it  to  ProDOS  8 
binary  format,  and  load  and  install  it  yourself.  See  "Writing 
Your  Own  Tool  Set,"  in  the  Apple  IIGS  Toolbox  Reference. 

□  Allow  your  program  to  be  launched  only  from  a  ProDOS  16- 
based  finder  or  launcher,  after  the  normal  ProDOS  16  boot 
sequence  has  loaded  all  the  RAM  patches  and  RAM  tool  sets. 

■  Switching  stacks  and  zero  pages:  You  have  a  standard  stack 
and  zero-page  available  in  emulation  mode,  but  you  also  need 
a  direct-page/stack  space  for  use  by  tool  sets  in  native  mode. 
Set  it  up  as  needed.  When  switching  from  emulation  mode  to 
native  mode  and  back,  you  must  save  the  current  value  of  the 
stack  pointer,  and  set  the  stack  pointer  to  the  proper  value  for 
the  mode  you  are  about  to  enter.  Likewise,  the  direct  register  is 
set  to  zero  upon  entering  emulation  mode;  you  must  save  its 
value  before  switching  to  emulation  and  restore  it  upon 
returning. 

For  detailed  instructions  on  saving  and  restoring  the  proper 
environment  while  switching  execution  modes,  see  "Notes  for 
Programmers"  in  the  Apple  IIGS  Firmware  Reference. 

■  Staying  in  bank  $00  or  disabling  interrupts:  Any  code  that  your 
program  calls  while  in  emulation  mode  must  be  in  bank  $00,  or 
else  interrupts  must  be  disabled.  The  Program  Bank  register  is 
not  saved  or  restored  when  an  interrupt  occurs  in  emulation 
mode. 
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Insert  parts  of  your  6502  code 


The  FWEntry  call  is  part  of  the 
Miscellaneous  Tool  Set.  See  the 
Apple  HGS  Toolbox  Reference. 


Because  the  65C816  processor  recognizes  the  6502  instruction  J 
it  may  be  possible  to  use  significant  sections  of  your  code, 
unchanged  or  only  slightly  modified,  in  a  native-mode,  ProDOS 
16-based  application.  That  is,  instead  of  making  a  hybrid 
application,  you  might  write  a  new  Apple  IIGS  application,  but 
save  time  by  incorporating  as  much  of  your  older,  6502-based 
code  as  possible.  In  most  cases  this  option  is  far  better  than 
writing  a  hybrid  application;  it  puts  ProDOS  16  and  the  tool  sets 
much  more  directly  at  your  program's  disposal. 

How  successful  you  can  be  depends  greatly  on  the  specific 
content  of  your  existing  code.  Routines  that  draw  to  the  screen  1 
otherwise  duplicate  the  tasks  performed  by  tool  sets  may  not  be 
worth  converting  to  native-mode  execution.  Code  that  uses 
absolute  address  references  or  that  must  itself  occupy  specific 
addresses  will  be  incompatible  with  native-mode  memory 
management.  Instructions  that  can't  reach  everywhere  in  the 
16-megabyte  Apple  IIGS  memory  space  (such  as  JSR  rather  than 
JSL)  can  cause  a  lot  of  problems,  depending  on  where  your  code 
and  data  are  and  what  system  features  you  need  to  access. 

In  spite  of  these  and  other  problems,  it  may  be  possible  to  use 
large  portions  of  certain  types  of  6502-based  code,  relatively 
unchanged,  in  native-mode  Apple  IIGS  applications.  Here  are  just 
a  few  considerations. 

■  Register  width:  In  most  cases  your  6502  code  will  require  short 
(8-bit)  accumulator  and  index  registers  when  running  in  native 
mode.  That  is,  the  m-  and  x-bits  need  to  be  set  (  =1)  when  the 
e-bit  is  cleared  (  =0).  However,  see  the  next  note. 

■  Stack  manipulation:  The  stack  pointer  value  is  commonly  saved 
and  restored  with  the  instruction  pair  TSX.  .  .TXS.  If  performed 
in  8-bit  mode,  this  sequence  destroys  the  high-order  byte  of  the 
stack  pointer.  To  be  safe,  do  all  stack  manipulation  with  16-bit 
registers. 

■  Firmware  entry  points:  Replace  all  calls  to  specific  firmware  I 
entry  points  with  FWEntry  tool  calls.  FWEntry  allows  you  while 
in  native  mode,  to  make  calls  to  (6502)  code  that  executes  in  1 
emulation  mode;  it  saves  and  restores  the  Data  Bank  and 
Direct  registers. 
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Data  and  buffer  allocation:  Remove  absolute  addresses  that 
define  your  data  buffers  or  other  entry  points.  For  example,  if 
your  program  reserves  a  4K  buffer  space  with  an  equate  such  as 
BUFFER   EQU   $  8  0  0  0 ,  replace  that  with  something  such  as 
BUFFER  DS    $10  00,  which  reserves  a  $1000-byte  buffer  but 
doesn't  require  it  to  start  at  address  $8000. 

Input/output:  I/O  in  a  standard  Apple  II  computer  takes  place 
by  accessing  locations  in  the  $Cxxx  address  space  (J/O 
memory).  In  the  Apple  IIGS,  I/O  memory  exists  only  in  banks 
$00,  $01,  $E0,  and  $E1.  Therefore,  if  your  code  is  running 
anywhere  in  expansion  RAM,  it  cannot  perform  I/O  unless  data 
accesses  to  $Cxxx  are  made  in  long  addressing  mode,  to  access 
the  proper  bank. 

However,  the  timing  of  much  I/O  is  critical  and,  because  a 
long-addressing  load  instruction  takes  an  extra  cycle  to  execute, 
you  may  not  be  able  to  change  the  addressing  mode. 

One  way  around  this  is  to  set  the  data  bank  register  to  $00 
before  executing  the  I/O  instructions.  Then,  however,  any  other 
data  in  the  same  bank  as  your  code  becomes  inaccessible — but 
that  may  not  be  a  problem  in  your  particular  case. 

There  are  many  other  alternatives,  including  creative  use  of  the 
direct  page  and  isolating  timing-critical  code,  that  can  be  useful 
in  various  individual  situations.  Every  situation  is  unique — feel 
free  to  be  creative. 


Rewrite  it  to  run  under  ProDOS  16 

Modifying  your  entire  program  for  full  16-bit  native  mode 
operation  on  the  Apple  IIGS  is  a  more  ambitious  task,  but  it  may 
well  be  worth  it  for  the  greater  number  of  features  you  can  access. 
In  order  to  run  entirely  in  native  mode,  under  ProDOS  16  and 
with  the  tool  sets  always  available,  your  program  needs  to 
consider  at  least  the  following  points. 

■  Managing  memory:  Because  the  Apple  IIGS  supports 
segmented  load  files,  one  of  the  first  decisions  to  make  is 
whether  and  how  to  segment  the  program  (both  the  original 
program  and  any  added  parts).  First,  make  your  code 
relocatable  so  the  Memory  Manager  can  control  where  it  is 
loaded.  You'll  need  to  specify  memory-block  attributes  in 
addition  to  modifying  your  code  as  described  in  the  previous 
section,  "Insert  Parts  of  Your  6502  Code." 
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Refer  to  the  detailed  descriptions 
In  Chapters  9  through  13  of  the 
Apple  IIGS  ProDOS  16  Referenced 
see  which  ProDOS  16  calls  are 
different  from  their  ProDOS  8 
counterparts. 


See  "Setting  Up  Direct- 
Page/Stack  Space,"  in 
Chapter  6. 


Object  module  format  is 
documented  In  the  Apple  liss 
Programmer's  Workshop 
Reference 


APW  is  discussed  in  Chapter  7. 


I 

III 


Memory  management  under  native-mode  operation  on 
Apple  IIGS  is  completely  different  from  standard-Apple  IlL 
methods.  If  your  program  allocates  its  own  memory  spaoB 
marks  it  off  in  the  ProDOS  8  global  page  bit  map,  the 
enhanced  version  must  be  altered  so  that  it  requests  all  needed 
space  from  the  Memory  Manager. 

i   Converting  operating-system  calls:  For  most  ProDOS  8  calls, 
there  is  an  equivalent  ProDOS  16  call  with  the  same  nameJ 
each  call  block  must  be  modified  for  ProDOS  16,  and  each 
parameter  block  must  be  reconstructed  in  the  ProDOS  l6| 
format. 

For  other  ProDOS  8  calls,  a  ProDOS  16  near-equivalent 
performs  a  slightly  different  task,  and  the  original  code  will 
have  to  be  changed  to  account  for  that. 

Yet  other  ProDOS  8  calls  have  no  equivalent  in  ProDOS  16.  II 
your  program  uses  any  of  these  calls,  they  will  have  to  be  1 
replaced  as  appropriate. 

i  Removing  global  page  references:  Any  access  your  original 

program  makes  to  the  ProDOS  8  global  page  must  be  replaced 
by  appropriate  ProDOS  16  or  toolbox  calls. 

i  Converting  stack  and  zero  page:  Under  ProDOS  16  in 
native  mode,  you  are  not  constrained  to  the  fixed  stack  arA 
zero-page  locations  provided  by  ProDOS  8  in  emulation  mode. 
You  may  either  let  ProDOS  16  assign  you  a  default  IK  direct- 
page/stack  space,  or  you  may  define  a  direct-page/stack 
segment  in  your  object  code.  In  either  case,  the  loader  may 
place  the  segment  anywhere  in  bank  $00 — you  cannot  expect 
any  specific  address  to  be  within  the  space. 

Assembling:  Once  your  source  code  has  been  modified  anfl 
augmented  as  desired,  you  need  to  reassemble  it.  You  mustusi 
an  assembler  (or  compiler,  for  high-level  languages)  that 
produces  object  files  in  Apple  IIGS  object  module  format  3 
(OMF);  otherwise  the  program  cannot  be  properly  linked  and 
loaded  for  execution.  Using  a  different  assembler  may  mean 
that,  in  addition  to  modifying  your  program  code,  you'll  have 
to  change  some  directives  to  follow  the  syntax  of  the  new  1 
assembler. 

If  you  have  been  using  the  EDASM  assembler,  you  will  notfl 
able  to  use  it  to  write  Apple  IIGS  programs.  Instead,  you  can  use 
the  Apple  IIGS  Programmer's  Workshop  (APW).  APW  is  a  set  o 
development  programs  that  allow  you  to  produce  and  edit  | 
source  files,  assemble/compile  object  files,  and  link  them  into 
proper  OMF  load  files. 
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I 


After  your  revised  program  is  linked,  assign  it  the  proper  Apple 
IIGS  application  file  type  (normally  $B3)  with  the  APW 
FileType  command. 


Start  from  scratch 

In  die  long  run,  this  is  the  best  alternative  in  most  cases.  Combing 
through  your  code  line-by-line  to  make  all  the  conversions 
described  in  the  previous  sections — even  if  it  works — will 
probably  yield  a  product  that's  only  half  successful.  Why  not  start 
fresh,  maintaining  your  original  design  and  concepts  but  writing 
new  code  that  truly  takes  advantage  of  the  power  and  convenience 
of  the  Apple  IIGS? 

The  purpose  of  this  book  has  been  to  show  you  that  it  is  both  easy 
and  rewarding  to  write  desktop  applications  for  the  Apple  IIGS.  It 
has  also  shown  you  that  such  applications  have  a  structure,  an 
approach  to  the  hardware,  and  a  user  interface  that  are 
fundamentally  different  from  those  of  traditional  Apple  II 
software.  Don't  confine  yourself  unnecessarily;  a  clean  slate  is  the 
best  way  to  start.  Take  advantage  of  the  freedom  the  Apple  IIGS 
gives  you! 
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Files  on  an  Apple  IIgs 
System   Disk 


A  system  disk  is  a  3.5-inch  disk,  5.25-inch  disk,  or  hard  disk  that 
has  the  files  necessary  for  an  Apple  IIGS  to  start  up  when  turned 
on  or  rebooted.  It  also  has  any  files  needed  to  support  the 
specific  application  programs  on  the  disk.  This  appendix  shows 
you  what  files  a  system  disk  must  have. 

Because  not  all  applications  have  the  same  needs,  not  all  system 
disks  are  alike.  In  particular,  there  are  complete  system  disks  and 
application  system  disks. 


Complete  system  disk 

Every  Apple  IIGS  user  (and  programmer)  needs  at  least  one 
complete  system  disk.  It  is  a  pool  of  system  software  resources, 
and  may  contain  files  missing  from  some  application  system 
disks.  Table  C-l  lists  the  contents  of  a  complete  system  disk. 

♦  Note:  The  word  complete  doesn't  mean  that  the  system  disk  has 
all  the  files  that  may  be  on  your  system  disk — only  that  it  has 
all  the  available  system  resources.  For  example,  most  system  I 
disks  include  files  containing  disk  utility  programs  or  finder- 
style  program  launchers.  Those  programs  aren't  considered 
here. 
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Table  C-l 

Contents  of  a  complete  system  disk 


Directory/File 


Description 


PRODOS 


SYSTEM/ 
P8 
P16 

START 
LIBS/ 
TOOLS/ 
FONTS/ 
DESK.ACCS/ 
DRIVERS/ 
SYSTEM. SETUP/ 
TOOL. SETUP 


ATINIT 
ATLOAD . 0 

BASIC. SYSTEM 

APPLETALK/ 


A  routine  that  loads  the  proper  operating  system  and  selects  an 
application,  both  at  boot  time  and  whenever  an  application  quits. 

A  subdirectory  containing  the  following  files: 

The  ProDOS  8  operating  system. 

The  ProDOS  16  operating  system  and  Apple  IIGS  System  Loader. 

The  first  program  executed:  typically  a  program  launcher  or  finder. 

A  subdirectory  containing  the  standard  system  libraries. 

A  subdirectory  containing  all  RAM-based  tool  sets. 

A  subdirectory  containing  all  fonts. 

A  subdirectory  containing  all  desk  accessories. 

A  subdirectory  containing  printer  and  port  drivers. 

A  subdirectory  containing  system  initialization  programs. 

A  permanent  initialization  file  containing  patches  to  ROM  and  a 
program  to  install  them.  This  is  the  only  required  file  in  the 
SYSTEM.  SETUP/  subdirectory;  it  is  executed  before  any  others  that 
may  be  in  the  subdirectory. 

A  permanent  initialization  file  that  initializes  the  AppleTalk  network. 

Another  file  for  AppleTalk  intialization. 

The  Applesoft  BASIC  system  interface  program. 

A  subdirectory  containing  files  supporting  the  built-in  Appletalk 
network  interface. 

The  complete  system  disk  is  an  800K  byte,  double-sided  3.5-inch 
disk;  the  required  files  will  not  fit  on  a  140K,  single-sided  5.25-inch 
disk.  However,  see  "Application  System  Disks"  (next). 

When  you  boot  a  complete  system  disk,  it  executes  the  file 
SYSTEM/ START. 


Complete  system  disk 
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The  SYSTEM.SETUP/  subdirectory 

The  SYSTEM.  SETUP/  subdirectory  may  contain  several  different 
types  of  files,  all  of  which  are  loaded  at  boot  time.  They  includi 
the  following. 

■  TOOL.SETUP:  This  file  must  always  be  present;  it  is  executed 
before  any  others  in  SYSTEM .  SETUP/.  TOOL .  SETUP  installs 
and  initiates  any  RAM  patches  to  ROM-based  tool  setsTI 
TOOL .  SETUP  is  finished,  ProDOS  16  loads  and  executes  the 
remaining  files  in  the  SYSTEM.  SETUP/  subdirectory,  which 
may  belong  to  any  of  the  categories  listed  below. 

■  Permanent  Initialization  files  (filetype  $B6):  These  files  are 
loaded  and  executed  just  like  standard  applications  (type  $B3), 
but  they  are  not  shut  down  when  finished.  They  also  must* 
certain  characteristics: 

□  They  must  be  loaded  in  nonspecial  memory. 

□  They  cannot  permanently  allocate  any  stack/direct-page 
space. 

□  They  must  terminate  with  an  RTL  (Return  from  subroutine 
Long)  rather  than  a  QUIT. 

■  Temporary  Initialization  files  (type  $B7):  These  files  are  loaded 
and  executed  just  like  standard  applications  (type  $B3),  and 
they  are  shut  down  when  finished.  They  must  terminate  with  an 
RTL  rather  than  a  QUIT. 

Although  they  are  loaded  and  installed  in  the  system  at  the  same 
time  as  the  files  in  SYSTEM. SETUP/,  desk  accessories  actually 
reside  in  the  subdirectory  DESK .  ACCS/.  There  are  two  types, 

■  New  desk  accessories  (type  $B8):  These  files  are  loaded  but  not 
executed.  They  are  put  in  nonspecial  memory. 

■  Classic  desk  accessories  (type  $B9):  These  files  are  loaded  but 

not  executed.  They  are  put  in  nonspecial  memory. 


Application  system  disks 

Each  application  program  or  group  of  related  programs  confl 
on  its  own  application  system  disk.  The  disk  has  all  of  the  system 
files  needed  to  run  that  application,  but  it  may  not  have  all  the 
files  present  on  a  complete  system  disk.  Different  applications 
may  have  different  system  files  on  their  application  system  disks 
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Table  C-2  shows  which  files  must  be  present  on  all  application 
system  disks,  and  which  files  are  needed  only  for  particular 
applications.  In  some  very  restricted  instances,  it  may  be  possible 
to  fit  an  application  and  its  required  system  files  onto  a  single- 
sided  (140K)  5.25-inch  disk;  most  applications,  however,  require  at 
least  one  double-sided  (800K)  3.5-inch  disk. 


Table  C-2 

Required  contents  of  an  application  system  disk 


Directory /File 


PRODOS 
SYSTEM/ 

P8 

P16 

START 

LIBS/ 

TOOLS/ 

FONTS/ 

DRIVERS 

DESK.ACCS/ 
SYSTEM. SETUP/ 

TOOL. SETUP 

BASIC. SYSTEM 

APPLETALK 

Important 


Required? 


Yes 

Yes 

(Required  if  the  application  runs  under  ProDOS  8) 

Yes 

(Required  if  a  START  file,  such  as  a  finder,  is  to  be  used) 

(Required  if  system  library  routines  are  needed) 

(Required  if  the  application  needs  RAM-based  tools) 

(Required  if  the  application  needs  fonts) 

(Required  if  the  application  does  any  printing  or  serial 
communication) 

(Required  if  desk  accessories  are  to  be  provided) 

Yes 

Yes 

(Required  if  the  application  is  written  in  Applesoft  BASIC) 

(Required  if  the  application  supports  printing  to  a  LaserWriter  or 
otherwise  uses  AppleTalk) 

The  files  PRODOS,  P8,  and  PI 6  all  have  version  numbers.  Whenever 
it  loads  an  operating  system  (at  startup  or  when  launching  an 
application),  PRODOS  checks  the  P8  or  P16  version  number  against 
its  own.  If  the  numbers  do  not  match,  it  is  a  fatal  error.  Be  careful  not 
to  construct  an  application  system  disk  using  incompatible  versions 
of  PRODOS,  P8,  and  PI  6. 


Application  system  disks 
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Appendix   D 


HodgePodge    Organization 


This  appendix  presents  three  topics  related  to  the  organization 
the  sample  program  HodgePodge. 

a  It  lists  all  HodgePodge  routines  and  their  source  files  for  all 
three  languages. 

°  a whSow"  lhe  rOUUneS  ^^  EXeCUte  Wh6n  Hod«ePod8e  opens 


□  It  discusses  and  lists  HodgePodge's  error-handling  procedures. 


HodgePodge  subroutines 


^v0"1  U,StS  a11  IIod8ePodge  routines.  Column  1  lists  in 
^^1  order,  each  routine  in  the  Pascal  version.  Column  2 

faZX      ^  n^  ***  PaSCd  rOUtine  is  in'  Colu™  3  and  4 
name  the  source  files  containing  the  equivalent  C  and  65816 

assembly-language  routines.  Column  5  gives  the  number  of  the 

and  Wd  r  ;        1 1***?  VCrSi°n  °f  each  routine  is  discuss^ 
and  listed.  Column  6  briefly  notes  what  each  routine  does. 
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Table  D-l 

HodgePodge  routines  (complete) 


Routine 

Pascal  file 

Cfile 

Assembly  file 

Listed  in ... 

Function 

AddToMenu 

MENU. PAS 

MENU.CC 

MENU. ASM 

Chap.  5 

adds  an  item 

AdjWind 

WINDOW. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  5 

deletes  an  item 

AskUser 

PAINT. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  5 

which  file  to  open 

CheckDiskError 

DIALOG. PAS 

DIALOG. CC 

DIALOG. ASM 

App.  D 

error  alert  box 

CheckFrontW 

EVENT. PAS 

EVENT. CC 

EVENT. ASM 

App.  G 

adjusts  menu  items 

CheckToolError 

DIALOG. PAS 

DIALOG. CC 

DIALOG. ASM 

App.  D 

system  failure 

DisableAll 

EVENT. PAS 

EVENT. CC 

EVENT. ASM* 

App.  G 

adjusts  menu  items 

Disableltems 

EVENT. PAS 

EVENT . CC 

EVENT. ASM* 

App.  G 

adjusts  menu  items 

DispFontWindow 

FONT. PAS 

FONT.CC 

FONT. ASM 

Chap.  2 

calls  text-draw 

DoAboutltem 

DIALOG. PAS 

DIALOG. CC 

DIALOG. ASM 

Chap.  4 

"About"  box 

DoChooseFont 

FONT . PAS 

FONT.CC 

FONT. ASM 

Chap.  3 

user  selects  font 

DoChooserltem 

PRINT. PAS 

PRINT. CC 

PRINT. ASM 

Chap.  5 

selects  printer 

DoCloseltem 

WINDOW. PAS 

WINDOW. CC* 

WINDOW. ASM 

Chap.  2 

closes  a  window 

DoMenu 

MENU . PAS 

MENU.CC 

MENU. ASM 

Chap.  2 

dispatches  menus 

DoOpenltem 

MENU. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  4 

to  open  a  window 

DoPrintltem 

PRINT. PAS 

PRINT. CC 

PRINT. ASM 

Chap.  5 

calls  printing 

DoQuitltem 

MENU. PAS 

EVENT. CC 

EVENT. ASM 

App.  G 

sets  quit  variable 

DoSaveltem 

PAINT. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  5 

to  save  a  file 

DoSetMono 

FONT . PAS 

FONT.CC 

FONT. ASM 

App.  G 

toggles  menu  item 

DoSetUpItem 

PRINT. PAS 

PRINT. CC 

PRINT. ASM 

Chap.  5 

user  page-setup 

DoTheOpen 

WINDOW. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  4 

opens  a  window 

DoWindow 

MENU. PAS 

WINDOW. CC 

WINDOW. ASM 

App.  D 

brings  window  to  front 

DrawTopWindow 

PRINT. PAS 

PRINT. CC 

PRINT. ASM 

Chap.  5 

printing  routine 

Enableltems 

EVENT. PAS 

EVENT. CC* 

EVENT . ASM* 

App.  G 

adjusts  menu  items 

FindMaxWidth 

•    * 

WINDOW. CC 

WINDOW. ASM 

App.  E,  F 

sizes  font  window 

HideAllWindows 

WINDOW. PAS 

WINDOW. CC 

WINDOW. ASM 

App.  G 

closes  windows 

HidePleaseWait 

DIALOG. PAS 

DIALOG.CC 

DIALOG. ASM 

Chap.  4 

hides  "wait"  dialog 

HodgePodge 

HP. PAS 

HP.CC* 

HP. ASM 

Chap.  2 

main  program 

InitGlobals 

GLOBALS.PAS 

HP.H* 

GLOBALS . ASM* 

Chap.  2 

initializes  variables 

LoadOne 

PAINT. PAS 

EVENT . CC 

10. ASM 

Chap.  6 

reads  a  picture  file 

MainEvent 

EVENT. PAS 

EVENT.  CC 

EVENT. ASM 

Chap.  2 

main  event  loop 

HodgePodge  subroutines 
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Table  D-l  (continued) 
HodgePodge  routines  (complete) 


Routine 

Pascal  file 

Cflle 

Assembly  file 

Listed  in... 

Function 

MakeATemplate 

DIALOG. PAS 

DIALOG. CC* 

DIALOG. ASM* 

Chap.  4 

creates  alert  items 

ManyWindDialog 

DIALOG. PAS 

DIALOG. CC 

DIALOG. ASM 

App.  G 

caution  alert 

MountBootDisk 

DIALOG. PAS 

DIALOG. CC 

DIALOG. ASM 

App.  D 

asks  user  for  disk 

OpenFilter 

PAINT. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  6 

alters  file  display 

OpenWindow 

WINDOW. PAS 

WINDOW. CC 

WINDOW. ASM* 

Chap.  4 

to  open  a  window 

Paint 

PAINT. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  2 

calls  picture-draw 

Paintlt 

PAINT. PAS 

WINDOW. CC 

WINDOW. ASM 

Chap.  3 

draws  picture 

SaveOne 

PAINT. PAS 

EVENT. CC 

10. ASM 

Chap.  6 

saves  a  picture  file 

SetUpDefault 

PRINT. PAS 

PRINT. CC 

PRINT. ASM 

Chap.  2 

makes  print  record 

SetUpForAppW 

EVENT. PAS 

EVENT. CC 

EVENT. ASM 

App.  G 

adjusts  menu  items 

SetUpForDAW 

EVENT. PAS 

EVENT. CC 

EVENT. ASM 

App.  G 

adjusts  menu  items 

SetUpMenus 

MENU. PAS 

MENU.CC 

MENU. ASM 

Chap.  2 

makes  menu  bar 

SetOpWindows 

WINDOW. PAS 

WINDOW. CC* 

GLOBALS.ASM* 

Chap.  2 

sets  size  &  loc. 

ShowFont 

FONT. PAS 

FONT.CC 

FONT. ASM 

Chap.  3 

draws  text 

ShowPleaseWait 

DIALOG. PAS 

DIALOG.CC 

DIALOG. ASM 

Chap. 4 

does  "wait"  dialog 

ShutDownTools 

HP. PAS 

HP.CC 

INIT.ASM 

Chap.  2 

shuts  down 

Start OpTools 

HP. PAS 

HP.CC 

INIT.ASM 

Chap.  2 

starts  all  tools 

*  Name  or  content  of 

routine  is  slightly  different  from  the 

Pascal  version. 

*  *  Does  not  exist  in  the  Pascal  version. 


Execution  sequence:  opening  a  window 

When  a  window  is  opened  in  HodgePodge,  several  routines  ar. 
called  in  sequence,  starting  with  DoOpenltem.  The  execution 
sequence  starts  out  in  the  same  way  whether  the  window  to  be 
opened  is  a  font  window  or  a  picture  window. 

The  routines  involved  with  opening  a  window  are  described  ir 
several  different  chapters  in  this  book.  To  help  you  follow  the 
sequence,  we  diagram  the  sequence  of  subroutine  calls  here,  for 
both  font  windows  and  picture  windows. 
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Opening  a  font  window 

A  font  window  is  opened  when  the  user  chooses  Display  Font 
from  the  Fonts  menu.  That  causes  execution  to  pass  to  the  routine 
DoOpenltem,  which  calls  OpenWindow.  OpenWindow  first  calls 
DoChooseFont,  then  DoTheOpen  to  actually  open  the  window. 

After  OpenWindow  is  finished,  DoOpenltem  calls  AddToMenu, 
and  then  execution  passes  back  to  the  main  event  loop.  See 
Figure  D-l. 

♦  Note:  The  dimmed  boxes  in  Figure  D-l  represent  routines 
called  to  open  a  picture  window  (Figure  D-2). 


DoOpenltem  - 


r   OpenWindow 


AddToMenu 


r  DoChooseFont 


DoTheOpen 


Figure  D-l 

Execution  sequence:  opening  a  font  window 


Opening  a  picture  window 

A  picture  window  is  opened  when  the  user  selects  Open  from  the 
File  menu.  Just  as  when  a  font  window  is  opened,  execution  passes 
to  the  routine  DoOpenltem,  and  to  OpenWindow. 

In  this  case  OpenWindow  calls  AskUser.  AskUser  first  calls 
SFGetFile — part  of  the  Apple  IIGS  Toolbox,  not  HodgePodge. 
SFGetFile  calls  the  ModgePodge  routine  OpenFilter  while  it  is 
displaying  filenames.  Once  a  filename  is  chosen,  AskUser  calls 
LoadOne  to  open  the  file.  OpenWindow  then  calls  DoTheOpen  to 
actually  open  the  window. 


Execution  sequence:  opening  a  window 
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After  OpenWindow  is  finished,  DoOpenltem  calls  AddToMenui 
and  then  execution  passes  back  to  the  main  event  loop.  See  Figure 
D-2. 

♦  Note:  The  dimmed  boxes  in  Figure  D-2  represent  routines 
called  to  open  a  font  window  (Figure  D-l). 


DoOpenltem 


OpenWindow 


AddToMenu 


DoChooseFont 


SFGetFile 


OpenRlter 


DoTheOpen 


LoadOne 


Figure  D-2 

Execution  sequence:  opening  a  picture  window 


Error  handling 

HodgePodge  has  three  routines  that  handle  error  conditions: 
CheckToolError,  MountBootDisk,  and  CheckDiskError. 
This  section  lists  them  and  discusses  what  they  do. 


CheckToolError 

CheckToolError  is  called  only  when  the  program  is  starting  up. 
It  is  a  very  simple  error  handler,  because  any  error  it  detects  is 
made  fatal,  and  because  it  puts  up  no  message  box  for  the  user.  In 
general,  CheckToolError  cannot  put  up  a  dialog  box  because 
the  Dialog  Manager  may  not  have  been  started  when 
CheckToolError  is  called. 
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CheckToolError  is  in  the  source  file 
DIALOG.PAS. 


CheckToolError  is  called  after  each  tool  startup  call.  It  checks 
the  value  of  the  global  variable  toolErrorNum;  if  the  number  is 
nonzero  an  error  has  occurred.  In  that  case  CheckToolError 
calls  the  System  Failure  Manager,  which  puts  up  the  "sliding 
apple"  error  screen  and  halts  execution. 

♦  Input:  CheckToolError  has  a  single  input  parameter:  an 
integer  location  number  that  specifies  what  part  of  the 
program  made  the  call.  Each  call  to  CheckToolError  passes 
a  different  integer.  The  integers  have  no  significance  or 
purpose  other  than  helping  the  programmer  locate  the  part  of 
the  source  code  that  generated  the  error. 


procedure  CheckToolError     (Where:    Integer); 


(begin   CheckToolError...} 


' 


toolErrorSave:  Integer; 
deathMsg    :  String; 


begin 
toolErrorSave  :=  ToolErrorNum; 
deathMsg    :  = 

1  At  SXXXX;  Could  not  handle  error  $•; 

if  toolErrorSave  <>  0  then 
begin 
Int2Hex  (Where, StringPtr (Longint 

(SdeathMsg) +6) ,4) ; 
SysFailMgr  (toolErrorSave, deathMsg) ; 
end; 
end; 


{string  to  display} 


{save  the  error  number} 
{This  is  the  message  with...} 
{...a  dummy  location  number} 

{If  there  HAS  been  an  error...} 

{...convert  loc.  no.  to  a  string., 
{...and  insert  it  in  message} 
{Then  go  to  system  failure) 
{end  of  IF  error  nonzero} 
{End  of  CheckToolError} 


MountBootDisk  is  in  the  source  file 
DIALOG.PAS. 


MountBootDisk 

MountBootDisk  is  called  during  the  loading  of  RAM-based  tool 
sets,  if  the  disk  containing  the  tool  sets  is  not  already  on  line. 
MountBootDisk  makes  use  of  the  Tool  Locator  routine 
TLMountVolume,  which  displays  a  dialog  box  prompting  the  user 
to  remount  the  boot  volume.  See  Figure  D-3. 
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function  MountBootDisk  :  integer; 

var     PromptStr  :  String; 
okStr    :  String; 
cancelStr  :  String; 
volStr   :  String; 
gbvParams  :  PathnameRec; 

begin 

PStstr=:7oKP,easeinsertthedisk,; 

cancelStr    :=    'Shutdown'; 
gbvParams.pathName    :=  @volStr; 

GET_BOOT_VOL    (gbvParams) ; 

MountBootDisk     •=   ttm™,-4.v    i 

K  •   ■iJ^MountVoluma  (174,30, 

promptStr,volStr, 
end;  okStr, cancelStr) ; 


(begin  MountBootDisk.. 


{string  to  appear  in  box} 
{title  of  OK  button  (=1)} 
{title  of  Cancel  button  (=2) } 
{define  pointer  to  volume  name} 

{find  the  boot  volume  name} 
{Call  Tool  Locator's  mount -volume...} 
{...routine;  it  returns  the  number  of...} 
...the  button  user  selects  (1  or  2)1 
{End  of  MountBootDisk} 


Please  insert  the  disk 
/SYSTEH.DISK/ 


Shutdown 


Figure  D-3 

TLMountVolume  screen  display 

♦  Note:  The  TLMountVolume  dialog  box  shown  in  Figure  D  3  is 
availabl  MSUme  that  the  DialoS  Manager  is 


call  d  afler  ever''  ProD°S  16  disk-access 
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CheckDiskError  Is  in  the  source  file 
DIALOG.PAS. 


CheckDiskError  notes  whether  the  previous  operation  caused 
an  error  and,  if  so,  puts  up  a  stop  alert  and  returns  TRUE  as  the 
function  result.  Otherwise  it  just  returns  with  a  value  of  FALSE. 

♦  Input:  CheckDiskError  has  a  single  input  parameter:  an 
integer  location  number  that  specifies  what  part  of  the 
program  made  the  call.  Each  call  to  CheckDiskError  passes 
a  different  integer.  The  integers  have  no  significance  or 
purpose  other  than  helping  the  programmer  locate  the  part  of 
the  source  code  that  generated  the  error. 


function  CheckDiskError  (Where :  Integer) 

: Boolean; 

var    itemClicked  :  Integer; 

ourAlert   :  AlertTemplate; 
ourErrStr   :  Str255; 
ourWhereStr  :  Str255; 
ourString   :  Str255; 
diskErrNum  :  Integer; 


{Begin  CheckDiskError...} 

{which  button  user  clicks} 
{defined  in  DIALOG.PAS} 
{error  number  to  display} 
{our  internal  error  code} 
{error  message} 
{error  number} 


begin 
diskErrNum   :=  ToolErrorNum; 
CheckDiskError  :=  (diskErrNum  <>  0) ; 

ourErrStr   :=  'XXXX'; 
ourWhereStr   :  =  'XX'; 
if  diskErrNum  <>  0  then 
begin 
Int2Hex  (diskErrNum, StringPtr ( 

Longlnt (@ourErrStr) +1) , 4) ; 
Int2Hex  (Where , StringPtr  ( 

Longlnt (@ourWhereStr)+l) ,2) ; 
ourString  : =  concat  ( ' Disk  Error  $ ' , 

ourErrStr, 
'  occurred  at  $ ' , 
ourWhereStr, 

' . ' )  ; 

MakeATemplate    (@ourAlert ,  fjourString)  ; 

InitCuroor; 

itemClicked    :=StopAlert (@ourAlert,NIL) ; 

end; 
end; 


{Save  the  global  error  number} 
{Assign  function  result: 
=  TRUE  if  error  nonzero} 
{dummy  chars,  to  set  length  byte} 
{dummy  chars,  to  set  length  byte} 


{Get  ASCII  string  of  error  no.} 

{Get  ASCII  string  of  our  code  no.} 
{Build  our  error  message...} 


{Build  a  template  for  the  alert} 
{restore  arrow  cursor} 
{Bring  up  the  alert  and  take 
the  user's  input} 
{end  of  IF  error  nonzero} 
{End  of  CheckDiskError} 


Error  handling 


309 


The  alert  box  put  up  by  CheckDiskError  is  shown  in  Figure  4-12. 

Note  that  CheckDiskError  calls  MakeATemplate  to  define  the 
features  (text  message  and  an  OK  button)  the  alert  box  will  have, 
MakeATemplate  is  described  under  "Constructing  Dialog  Boxes 
and  Alerts"  in  Chapter  4. 
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HP.ASM  (main  program) 


*************************************************** 


*********** 


HodgePodge:   An  example  Apple  IIGS  Desktop  application 

Written  in  65816  Assembler  by  the  Apple  IIGS  Development  Team 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


This  program  and  its  derivatives  are  licensed  only  for 
use  on  Apple  computers. 

Works  based  on  this  program  must  contain  and 
conspicuously  display  this  notice. 

This  software  is  provided  for  your  evaluation  and  to 
assist  you  in  developing  software  for  the  Apple  IIGS 
computer. 

This  is  not  a  distribution  license.  Distribution  of 
this  and  other  Apple  software  requires  a  separate 
license.  Contact  the  Software  Licensing  Department  of 
Apple  Computer,  Inc.  for  details. 

DISCLAIMER  OF  WARRANTY 

THE  SOFTWARE  IS  PROVIDED  "AS  IS"  WITHOUT 
WARRANTY  OF  ANY  KIND,  EITHER  EXPRESS  OR  IMPLIED, 
WITH  RESPECT  TO  ITS  MERCHANTABILITY  OR  ITS  FITNESS 
FOR  ANY  PARTICULAR  PURPOSE.   THE  ENTIRE  RISK  AS  TO 
THE  QUALITY  AND  PERFORMANCE  OF  THE  SOFTWARE  IS  WITH 
YOU.   SHOULD  THE  SOFTWARE  PROVE  DEFECTIVE,  YOU  (AND 
NOT  APPLE  OR  AN  APPLE  AUTHORIZED  REPRESENTATIVE) 
ASSUME  THE  ENTIRE  COST  OF  ALL  NECESSARY  SERVICING, 
REPAIR  OR  CORRECTION. 

Apple  does  not  warrant  that  the  functions 
contained  in  the  Software  will  meet  your  requirements 
or  that  the  operation  of  the  Software  will  be 
uninterrupted  or  error  free  or  that  defects  in  the 
Software  will  be  corrected. 

SOME  STATES  DO  NOT  ALLOW  THE  EXCLUSION 
OF  IMPLIED  WARRANTIES,  SO  THE  ABOVE  EXCLUSION  MAY 
NOT  APPLY  TO  YOU.   THIS  WARRANTY  GIVES  YOU  SPECIFIC 
LEGAL  RIGHTS  AND  YOU  MAY  ALSO  HAVE  OTHER  RIGHTS 
WHICH  VARY  FROM  STATE  TO  STATE. 


*   ASM65816  Code  file  "HP.ASM"  —  Main  routine  and  COPY'S  for  other  files 

t«H*.«tt.Ht....«,«1„»li..«lt»l,H..«H».l,«.*..4,«,,»„„i„„H,„ 
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************************************ 


Version  1.0  —  August  1987 


************* 


******************** 


ABSADDR  ON 
KEEP  HP 
MCOPY    HP. MACROS 


********************** 


************************************** 


*    The  main  program 
* 

**************************************************************** 
Hodgepodge  START 

using  GlobalData 


Global  equates  used  throughout   the  program. 


True 
False 


gequ  $8000 
gequ  $0000 


;  Set  the  data  bank  to  code  bank    so   I   can  use  absolute 
;  addressing. 


phk 
plb 


;  Save  address  of  D  for  use  later 

tdc 

st a  MyZP 


Load  Init  everything. 


pha 

PushWord  *$0080 

jsl  StartupTools 

pla 


pla 

bne  AllDone 

jsr  SetupMenus 


;  Initialize  system  flags. 

stz  LastWType 
stz  QuitFlag 
stz  Windex 


mode  to  use  for  QD 

/Necessary  because  StartUpTools 
;uses  Pascal  calling  convention 
; leaving  input  params  on  stack 
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Zero  the  print  record  handle. 

stz  PrintRecord 
stz  PrintRecord+2 


Take  events  until  user  quits, 
jsr  MainEvent 


All  is  done,  let's  shut  down. 

AllDone        anop 

jsl  ShutDownTools 


PushLong  PrintRecord     ;  get  rid  of  print  record  handle 

_DisposeHandle  ;  if  PrintRecord  has  zero  in  it 

;  dispose  handle  will  fail  but 

;  we  don't  care. 

_Quit  QuitParams 

END 


COPY 

7/E1 6. WINDOW 

COPY 

7/E16. DIALOG 

COPY 

INIT.ASM 

COPY 

EVENT. ASM 

COPY 

MENU. ASM 

COPY 

WINDOW. ASM 

COPY 

DIALOG. ASM 

COPY 

FONT. ASM 

COPY 

PRINT. ASM 

COPY 

10. ASM 

COPY 

GLOBALS.ASM 
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INI 


NIT.ASM  (Initialization) 


^******** 


Hodgepodge:   An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


ASM65816  Code  file  "INIT.ASM"  —  Toolbox  startup/shutdown  routines 


INIT.ASM 

Contains  the  following  global  data 
MylD  Variable  holding  userid  of  this  program 

ThisMode        Variable  holding  mode  used  to  start 

QuickDraw 
OrigPort        Variable  holding  pointer  to  original 

port  that  QuickDraw  has  when  started  up. 

Contains  the  following  private  data 

ZPHandle        Holds  handle  to  memory  that  is  used 

as  direct  page  for  the  tools. 
ZPPtr  Pointer  to  above  memory. 

Contains  the  following  public  procedures. 

function  StartupTools   (ModeToUse  :  SCB_type)  :  integer; 

Starts  up  the  tools  (initializing  quickdraw  with  the  specified 
mode)  and  initializes  the  global  variables  above. 

procedure  ShutdownTools; 

Shuts  things  down,  undoing  what  was  done  above. 

*  Uses  the  MountBootDisk  dialog  routine  to  have  the  user  put  the 

*  system  disk  on  line. 

*  Uses  the  CheckToolError  dialog  routine  to  cause  a  system  death 

*  (bouncing  apple)  if  the  A  register  is  nonzero.  The  X  register  is 

*  assumed  to  contain  a  "Where"  value. 

*  Change  History 

*  June   1987  Steven  E.  Glass 

*  August  1987  Ben  Koning 

*  Modified  to  use  the  C  calling  convention  so  that  can  be  used  by 

*  both  C  and  TMLPascal.   (Input  parameters  are  not  removed  from 

*  the  stack.) 
* 
***************************************************************** 
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InitDummy      START 

COPY  7/E16. MEMORY 

END 

*  Start upTools 

* 

*  Input:    ModeToUse  —  $0080  for  640  mode 

*  Output:    ErrorCode  —  Error  if  nonzero 

*  (NOTE:  DIFFERENT  FROM  C  AND  PASCAL  VERSIONS) 

*  Calling  Sequence: 

Pna  ;  space  for  output 

PushWord  #Mode     ;  Mode  to  use  for  QD 

*  jsl  StartupTools 

Plx  ;  remove  input  parameter 

P^a  ;  get  func  result 

*  bne  MustQuit 
* 

*  This  is  a  subroutine  to  load  and  startup  all  the  tools 

*  an  application  generally  needs.   This  routine  also  gets  the 

*  space  in  bank  zero  that  the  tools  use  for  direct  page.   The 

*  only  time  an  error  code  other  than  zero  is  returned  is  when 

*  the  boot  disk  is  not  on  line  and  the  user  asks  to  cancel 

*  rather  than  to  put  it  on  line. 

*  Order  of  work: 

*  1)   Start 

Tool  Locator,  Memory  Manager,  Misc  Tools 

*  QuickDraw,  Event  Manager 

*  2)   When  these  are  running,  the  "One  moment  please"  string  is 

*  displayed  and  LoadTools  is  called. 

*  QuickDraw  and  the  Event  Manager  are  started  up  first 

*  because  if  the  LoadTools  call  returns  a  VolNotFound  error 

*  we  need  to  have  the  volume  mounted.   This  is  done  with 

*  the  TLMountVolume  call  which  requires  both  QuickDraw  and 

*  the  Event  Manager  to  be  active. 
* 

*  3)   Next  I  start  up 

Window  Manager,  Control  Manager, 

Menu  Manager,  LineEdit,  Dialog  Manager 

*  4)   After  these  are  initialized,  I  setup  and  draw  the 

*  menu  bar  and  display  a  message  to  the  user  before  I 

*  initialize  the  rest  (standard  File,  Font  Manager, 

*  QuickDraw  Auxiliary  and  print  manager) . 

StartupTools   START 

using  InitData 

ModeToUse      equ   $5 
ResultCode     equ   $7 
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Direct  Page  use.      The   following  eguates 
describe  how  the  direct  pages  are  assigned 
to  the  tools  below. 


DPForQuickDraw  equ  $000 

DPForEventMgr  equ  $300 

DPForCtlMgr  equ  $400 

DPForLineEdit  equ  $500 

DPForMemiMgr  equ  $600 

DPForStdFile  equ  $700 

DPForFontMgr  equ  $800 

DPForPrintMgr  equ  $900 


needs  3 
needs  1 
needs  1 
needs  1 
needs  1 
needs  1 
needs  1 
needs  2 


TotalDP 


equ   $B00 


Just   in  case  this  routine   is   called  when  the 
data  bank  is   set   somewhere  else  we  set    it 
right  here. 

phb 

phk 
plb 


Copy  the  input  parameter  into  the  global 
data  area  and  initialize  the  result  code 
assuming  all   is  well. 

Ida  ModeToUse,s 
sta  ThisMode 


Ida  #0 

sta  ResultCode, s 


Start  with  TLStartup 

JTLStartup 


Tool  Locator 


Initialize  the  memory  manager. 


PushWord  #0 

_MMStartup 

ldx  #1 

jsr  CheckToolError 

pla 

sta  My  ID 


Initialize  misc  tools. 


_MTStartup 

ldx  #2 

jsr  CheckToolError 
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First  get  some  memory  for  the  zero  page  we  need! 

pha  ;  space  for  handle 

pha 

PushLong  #TotalDP 

PushWord  MylD 

PushWord  #attrBank+attrPage+attrFixed+attrLocked 

PushLong  #0 

_NewHandle 

ldx  #3 

jsr  CheckToolError 


Take  the  resulting  handle  (still  on  the  stack) 
and  dereference  it,  putting  the  pointer  into 
ZPPtr. 


phd 

tsc 

ted 

Ida 

[3] 

sta 

ZPPtr 

pld 

pla 

sta 

ZPHandle 

pla 

sta 

ZPHandle+2 

;  save  current  D 

;  turn  stack  into  direct  page 

;  deref  the  pointer 

;  we  know  that  high  word  is  0 

;  restore  direct  page 

;  put  handle  into  storage 


Note  that  width  on  startup  is  320  to  allow  doubling  the 
screen  width  when  doing  best  printing. 

Ida  ZPPtr 

clc 

adc  #DPForQulckDraw 

pha 

PushWord  ThisMode 

PushWord  #320  ;  max  size  of  scan  line  in  bytes 

PushWord  MylD 

_QDStartup 

ldx  #4 

jsr  CheckToolError 

PushLong  #0 
_GetPort 
PullLong  OrigPort 

ldy  #640 
Ida  ThisMode 
emp  #$80 
beq  okmode 
ldy  #320 
okmode         anop 

sty  MaxX 

Ida  ZPPtr 

clc 

adc  #DPForEventMgr 

pha 
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PushWord  #20 
PushWord  #0 
PushWord  MaxX 
PushWord  #0 
PushWord  (200 
PushWord  MylD 
_EMStartup 

ldx  #5 

jsr  CheckToolError 


;  queue  size 

;  x  clamp  low 

;  x  clamp  high 

;  y  clamp  low 

;  y  clamp  high 


Put  up  a  string  telling  user  that  something  is 
happening. 

PushWord  #20 
PushWord  #20 
_MoveTo 

PushWord  #0 
_SetBackColor 

PushWord  #$F 
_SetForeColor 

PushLong  #MomentStr 
_DrawString 

ShowCursor 


Make  the  LoadTools   call 


LoadAgain 


_GET_FILE_INFO  ParamBlock 
bcc  OkToLoad 

jsr  MountBootDisk 

cmp  #1 

beq  LoadAgain 


sta  ResultCode,s 
brl  GetOut 


OkToLoad      PushLong  #ToolTable 
_LoadTools 
bcc  ToolsLoaded 

ldx  #6 

jsr  CheckToolError 


;Try  to  find  the  directory 

; "/SYSTEM/TOOLS/.   Ok?  Go  load. 

;Else,  display  psuedo-dialog 
;Did  they  select  "OK" 3 
,-Yes,  so  try  it  again. 

;Else,  they  selected  "Cancel". 
;So  return  result  code 
;and  leave  this  routine. 

;Push  address  of  tool  table 
;Attempt  to  load  them  (should 
;work) .   If  ok,  go  on. 

;If  error  happened  anyway, 
;we'll  just  die  here. 


The  tools  are  loaded  so  start  them  up. 

ToolsLoaded    anop 

_QD Aux  St  a  rt  up 


WaitCursor 


PushWord  MylD 
_WindStartup 

ldx  #7 


;  QuickDraw  Auxiliary 

;  With  QDAux  started  we  can  show  the 

;  watch  cursor 

;  Window  Manager 
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jsr  CheckToolError 

PushLong  #$0000 
_RefreshDeskTop 

PushWord  My ID 

Ida  ZPPtr 

clc 

adc  #DPForCtlMgr 

pha 

_CtlStartup 

ldx  #8 

jsr  CheckToolError 

PushWord  My ID 

Ida  ZPPtr 

clc 

adc  #DPForLineEdlt 

pha 

_LEStartup 

ldx  #9 

jsr  CheckToolError 

PushWord  MylD 
_DialogStartup 

ldx  #10 

jsr  CheckToolError 

PushWord  MylD 

Ida  ZPPtr 

clc 

adc  #DPForMenuMgr 

pha 

_MenuStartup 

ldx  #11 

jsr  CheckToolError 

_DeskStartup 

jsr  ShowPleaseWalt 

ldx  #12 

jsr  CheckToolError 

PushWord  MylD 

Ida  ZPPtr 

clc 

adc  #DPForStdFile 

pha 

_SFStartup 

ldx  #13 

jsr  CheckToolError 

PushWord  #$8000 
_SFAllCaps 

PushWord  MylD 

Ida  ZPPtr 

clc 

adc  #DPForFontMgr 

pha 

_FMStartup 


display  desktop 
Control  Manager 


LlneEdlt 


Dialog  Manager 


Menu  Manager 


Desk  Manager 
Message  for  user 

Standard  File 


display  file  names  In  all  caps 
Font  Manager 
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ldx  #14 

jsr  CheckToolError 

PushWord  My ID 

Ida  ZPPtr 

clc 

adc  #DPForPrintMgr 

pha 

_PMStartup 

ldx  #15 

jsr  CheckToolError 

jsr  HldePleaseWalt 

InitCursor 


Print  Manager 


reset  cursor  to  arrow  cursor 


All  is  done.  We  must  clean  up  the  stack  and  get  out 


MomentStr 

MaxX 

ParamBlock 


anop 
plb 

rtl 

str  'One  moment  please...' 
ds  2 


restore  dbr 
all  done. 


;ProDOS/16  Parameter  block 

;With  pathname  as  Input;  rest  of  the 

/fields  will  be  set  as  output. 


dc  14'PathName' 

ds  2 

ds  2 

ds   4 

ds  2 

ds  2 

ds  2 

ds  2 

ds  2 

ds   4 

str  •* /SYSTEM/TOOLS' 

END 


*  *  *  *****************************  *************** 


PublicInitData 

These  are  global  variables  available  to  the  main  program. 


************* 


************************** 


PublicInitDATA  DATA  -Global 


Public  Variables 


MylD 

ENTRY 

ds   2 

ThisMode 

ENTRY 

ds   2 

OrigPort 

ENTRY 

ds   4 

END 
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InitData 
ZPHandle 
ZPPtr 

ToolTable 

StartTable 


PrivDATA 
ds  4 
ds  4 


a  nop 
a  nop 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 


dc 
dc 
dc 


EndTable 


dc  i 
dc  i 

dc  i 
a  nop 

END 


(EndTable- 
'1,S0101' 
'2, $0101' 
'3, $0101' 
'4, $0101' 
'5, $0100' 
"6, $0100' 
'14, $0103' 
'15, $0103' 
'16,$0103' 
'18, $0100' 
19,$0100' 
20, $0100' 
21, $0100' 
22, $0102' 
23, $0100' 
27, $0100' 
28, $0100' 


StartTable) /4 ' 

;  tool  locator 
;  memory  manager 
;  misc  tools 
;  quickdraw 
;  desk  manager 
;  event  manager 
;  window  manager 
;  menu  manager 
;  control  manager 
;  quickdraw  aux 
;  print  manager 
;  line  edit 
;  dialog  manager 
;  scrap  manager 
;  standard  file 
;  Font  manager 
;  List  manager 


**************** 
* 

*  ShutDownTools 

*  Inputs:    None 

*  Outputs:   None 


************** 


**************** 


r********** 


*  Shuts  down  every  thing  started  up  in  InitTools 
*******  ************************* 


*************** 


ShutDownTools  START 

using  InitData 

_DeskShutdown 

_FMShutDown 

_PMShutdown 

_SFShutDown 

_DialogShutdown 

_LEShutdown 

_MenuShutDown 

_WindShutDown 

_Ctl Shutdown 


_EMShutDown 

_QDAuxShutdown 

_QDShutDown 


shut  this  first  so  that  other  tools 
are  still  around  (close  DA's) 


this  is  shut  down  after  window  mgr 
because  window  mgr  makes  contol 
manager  calls  at  shutdown  time 
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_MTShutdown 

PushLong  ZPHandle        ;  get  rid  of  handle  for  direct 
_DisposeHandle  ;  page 

PushWord  MylD 
_MMShutdown 

_TLShutdown 

rtl 
END 
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* ******************* 


* *************** 


****  ****** 


HodgePodge:   An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


ASM65816  Code  file  "MENU.ASM"  ~  Menu  initialization  and  dispatching. 


****************** 


*********************** 


********** 


*************************** 

*  Menu  item  ID'S 
********************************** 


************* 


********* 


*************************** 


AppleMenuID  gequ  1 

FileMenuID  gequ  2 

EditMenuID  gequ  3 

WindowsMenuID  gequ  4 

FontsMenuID  gequ  5 


UndoID 

gequ 

250 

Cut  ID 

gequ 

251 

CopylD 

gequ 

252 

PastelD 

gequ 

253 

ClearlD 

gequ 

254 

CloseWID 

gequ 

255 

AboutID 

gequ 

256 

Quit ID 

gequ 

257 

OpenWID 

gequ 

258 

SavelD 

gequ 

259 

ChooselD 

gequ 

260 

SetupID 

gequ 

261 

PrintID 

gequ 

262 

ShowFontID 

gequ 

263 

Mono ID 

gequ 

264 

end 

These  next  6  are  standard  and 
required  for  DA  support  under 
TaskMaster. 


These  are  our  own  responsibility 


* 

*  DoMenu 

* 

*  Called  when  TaskMaster  tells  me  that  a  menu  item  has 

*  been  selected. 

* 

*********************************************************** 
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DoMenu 


START 

using  GlobalDATA 


DoWitem 


Ida  TaskDATA 

cmp  #2  99 

beq  Unhilite 

bge  DoWitem 

sec 

sbc  lUndoID 

asl  a 

tax 

jsr  (MenuTable,x) 


299  is  dummy  do  nothing  -  ignore 
do  nothing 

300  and  up  are  added  windows 


Unhilite  anop 

PushWord  #False 
PushWord  TaskDATA+2 
HiliteMenu 


draw  normal 
which  menu 


rts 


MenuTable 


anop 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  1 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 
dc  i 


' ignore ' 

' ignore' 

' ignore ' 

' ignore' 

' ignore ' 

'doCloseltem' 

'doAboutltem' 

'doQuitltem' 

'doOpenltem' 

'doSaveltem' 

' doChooserltem' 

'doSetupItem' 

'doPrintltem' 

•doOpenltem' 

• doSetMono ' 


Edit  items 


ProcessW 


sec 

sbc 

#300 

anop 

asl 

a 

asl 

a 

tax 

Ida 

windowlist,x 

sta 

WhichWindow 

Ida 

windowlist+2,x 

sta 

whichwindow+2 

jsr 

dowindow 

jrap 

unhilite 

END 

;  In  A  is  window  number 


times  4  to  index  window  list 


;    done  with   it 


MENU.ASM  (menus) 
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r*"— **************************.*******„______ 

*  SetupMenus 

*  Now  build  the  menu  bar  by  insert!™  i-v.        , 

*  (back   to   front).  inserting  the  six  menus 

* 

SetupMenus     START  ************************* 

using  MenuDATA 

PushLong  #0  .  _, 

PushLong  #FontsMenu      '   P  Ce  f°r  retUrn 

_NewMenu 

PushWord  #0 

_InsertMenu 

PushLong  #0 

PushLong  #WindowsMenu    '  ^^  *"  return 

_NewMenu 

PushWord  #0 

_InsertMenu 

PushLong  #0 

PushLong  *EditMenu       '  "^^  f°r  retUrn 

_NewMenu 

PushWord  #0 

_InsertMenu 

PushLong  #0 

PushLong  #FlleMenu       '  ^^  f°r  retUrn 

_NewMenu 

PushWord  #0 

_InsertMenu 

PushLong  #0 

PushLong  #AppleMenu      '  ^^  f°r  retUrn 

_NewMenu 

PushWord  #0 

_InsertMenu 


Call  the  desk  accessory  manager  to  install  fh„ 
list  of  NDAs  in  the  system.  "  the 


PushWord  #1 
_FixAppleMenu 


Finish  off  getting  the  menu  bar  ready. 

/Discard  menu  bar  height 
'Set  starting  position  o 

/Actually  draw  the  menu  bar 


PushWord  #0 
_FixMenuBar 
pla 

PushWord  #10 

_SetMTitleStart  starting  position  of  menu 


_DrawMenuBar 

rts 


END 
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Language 


********** 


:  AddToMenu: 

Use  the  fact  that  the  last  SFGTEFILE  returned  in  REPLY  record 

the  name  of  the  file  and  the  state  of  the  request.   Set  PrintAvail. 


********** 


AddToMenu  START 

using  GlobalDATA 

Ida  #1 

sta  PrintAvail 

pushlong  #0 

_FrontWindow 

pla 

sta  whichwindow 

plx 

stx  whichwindow+2 

PUSHLONG  #0 
PUSHLONG  whichwindow 
_GetWrefCon 

pla 

sta  Temphandle 

plx 

stx  TempHandle+2 

jsr  Deref 
sta  0 
stx  2 

PushWord  Windex 

PushLong  #Iddgt 

PushWord  #2 

PushWord  #0 
Int2Dec 


Ida 

iddgt 

ora 

#'00' 

sta 

iddgt 

ldy 

#oLength 

Ida 

[0],y 

and 

#$FF 

clc 

adc 

#6 

tay 

ldx 

#0 

Ida 

idn,x 

sta 

[0],y 

iny 

iny 

inx 

inx 

cpx 

16 

bne 

cpyidlp 

Ida 

0 

clc 

adc 

#4 

tax 

Ida 

2 

adc 

#0 

pha 

,-Set  PrintAvail  flag  to  allow  printing 
;it's  the  front  window  we're  adding  in 

;get  result  for  pushing  in  a  sec. 
; space  for  result 
;refcon  has  handle  to  data 


dereference 


; font's  size 
;ptr  to  string 

; length  of  string 
/unsigned  integer 
; convert  size  into  an  ASCII  string 


,-get  names  length 

; f ind  end  of  string  to  slide  stuff 


y  index  off  ids  is  where  we  store 
x  index  off  idn  is  where  we  load 


;  do  6  bytes 

,-now  pt.  to  itemlist  loc.  for  insert 


MENU.ASM  (menus) 
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NotFirstTime 


phx 

PUSHWORD  #$FFFF 
PUSHWORD  IWindowsMenuID 
_InsertMItera 

Ida  windex 
bne  NotFirstTime 
PushWord  #299 
_DeleteMItem 

Pushword  #$ff7f 
PushWord  IWindowsMenuID 
_SetMenuFlag 

Lda  I  True 

St a  NeedToUpdate 

Ida  #0 

pha 

pha 

PushWord  IWindowsMenuID 

_CalcMenuSize 

Ida  Windex 

asl  a 

asl  a 

tax 

Ida  whichwindow 

sta  WindowList,x 

tay 

Ida  whichwindow+2 

sta  WindowList+2,x 

inc  windex 

Ida  temphandle 
ldx  temphandle+2 
jsr  unlock 

rts 


idn 

dc 

c'\N3 

iddgt 

dc 

c'00' 

idcr 

dc 

il'13 

iddray 

dc 

il'O' 

if  first  time,  omit  dummy  299 

299  is  dummy  item  to  delete 
;  it's  gone,  now  add  next  one 


re-calc  size 

save  off  window  Pointer  for  menu  stuff 
*4  for  WINDOWLIST  index 

bump  counter  for  next  add  on 
ok,  let  this  loose  again 


;  "\N3nn"  will  slide  in  behind  it 

;00->15  slides  into  nn 

;and  finally  a  carriage  return 

;a  dummy  so  we  slide  exactly  8 


END 
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******** 


*  Menu  Data 


********* 
MenuData 


Return 


equ  13 


AppleMenu  dc  c'»@\XH' ,i 'AppleMenuID' ,  11 'RETURN' 

dc  c'==About   HodgePodge. . .\H' , i'AboutID' 
dc    c'=— \N500D\0'  ,il' RETURN' 
dc  c' . ' 


11' RETURN' 


EdltMenu  dcc'»      Edit      \DH' ,  i 'EdltMenuID' ,  11 '  RETURN' 

dc   c'==Undo\*ZzH' ,1'UndoID' , il' RETURN' 
dc    c'==-\N500D\0' ,11" RETURN' 
dc    c ' — Cut\*XxH ' , 1 ' Cut ID ' , 11 ' RETURN ' 


dc 
dc 

dc 
dc 


•  —Copy  \  *CcH '  ,  1 '  Copy  ID  '  ,  11 '  RETURN  ' 
• ==Paste\*VvH' , 1 ' PastelD' , 11 ' RETURN' 
' ==Clear\H ' , 1 ' ClearlD ' , 11 ' RETURN ' 


FlleMenu  dc  c'»     File      \H' ,  i  '  FileMenuID' ,  11  'RETURN' 

dc  c'=-Open. . .\*OoH', 1'OpenWID' , il" RETURN' 
dc   c ' ==Close\DH ' , i ' CloseWID ' , il ' RETURN ' 
dc  c ' ==Save  As . . . \DH ' , i ' SavelD ' , 11 ' RETURN ' 
dc   c'=— \N500D\0',il'RETURN' 

dc  c'==Choose  Printer. . .\H' , i 'ChooselD' , il' RETURN' 
dc  c'—Page   Setup.  .  .\DH' ,  1 '  Set upID' ,  il 'RETURN' 
dc  c'==Prlnt. . . \D*PpH' , 1 'Print ID' ,11 'RETURN' 
dc    c'=—  \N500D\0'  ,11'RETURN' 
dc    c'=-Quit\*QqH'  ,  i'CjuitID',il  'RETURN' 
dc  c' . ' 

WindowsMenu  dc  c'»     Window     \DH' ,  1 'WindowsMenuID' ,  il 'RETURN' 

Origltem  ENTRY 

dc  c'-=No  Windows   allocated\N299' ,il' RETURN' 
dc  c' . • 

FontsMenu  dcc'»      Fonts      \H' ,  i 'FontsMenuID' ,  il '  RETURN' 

dc  c'==Display  Font. . .\*FfH', 1 'ShowFontID' ,11 'RETURN' 

MonoPropItem       ENTRY 

dc  c'==Display  Font   as  Mono-spaced\*MmH' , 1 'MonoID' , il 'RETURN' 

dc  c' . ' 
MonoStr  dc  c'-=Display  Font   as  Mono-spaced\H" ,  1 'MonoID' ,  il 'RETURN' 

PropStr  dc  c'~Display  Font  as   Proportional\*MmH' ,  i'MonoID' ,il 'RETURN' 


******NOTE:    300   is   starting  number   for  a  building  list  -   used  in  AddToMenu 
******  299   is  the  dummy  one  that   is  deleted  when  we   get   a   real   one 


MENU.ASM  (menus) 
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EVENT.ASM  (main  event  loop) 


********** * 


it************, 


Hodgepodge:   An  example  Apple  nGS  Desktop  appllcatl 


**************** 

on 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc 
All  Rights  Reserved 


ASM65816  Code  file  "EVENT.ASM"  — 


TaskMaster  call;  Dispatching  to  all 
other  routines;  Menu  dimming. 


*********** 


""""*»««««***.*..**.«*«.M„„„„M.„„„„M„,M„rt(kM^* 


************** 
*  Event 


************ 


*  This  contains  the  main  event  loop. 


*************, 


*************** 


***************** 


MainEvent 

START 

using  GlobalData 

Again 

anop 

Ida  QuitFlag 
bne  AllDone 

jsr  CheckFrontw 

PushWord  #0 
PushWord  #$FFFF 
PushLong  #EventRecord 
_TaskMaster 

pla 

beq  Again 

asl  a 
tax 

jsr  (TaskTable, x) 

bra  Again 

AllDone 

rts 

TaskTable 

anop 

;  Event  manage 

c   events 

dc  i' ignore' 
dc  i' ignore' 
dc  i' ignore' 
dc  i' ignore' 


;Has  Quit  been  select? 
;...  if  so,  stop  the  loop. 

; Handle  the  menu  dis/enable 


;No  event?  loop. 


/Multiply  by  two... 

;use  for  index  into... 

/dispatch  table  to  execute  events 

;Loop. 


;  0  null 

,"  1  mouse  down 

;  2  mouse  up 

;  3  key  down 
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dc 

i 

ignore ' 

dc 

i 

ignore' 

dc 

i 

ignore' 

dc 

i 

ignore1 

dc 

i 

DoActivate 

dc 

1 

ignore' 

dc 

i 

ignore' 

dc 

i 

ignore' 

dc 

i 

ignore ' 

dc 

i 

ignore ' 

dc 

i 

ignore' 

dc 

i 

ignore' 

4 

undefined 

5 

auto-key  down 

6 

update  event 

7 

undefined 

8 

activate 

9 

switch 

10 

desk  ace 

11 

device  driver 

12 

ap 

13 

ap 

14 

ap 

15 

ap 

Task  master  events 


dc  i1 ignore'            , 

0  in  desk 

dc  i'DoMenu'            , 

1  in  MenuBar 

dc  i' ignore1            , 

2  in  system  window 

dc  i' ignore'            , 

3  in  content  of  window 

dc  i' ignore' 

4  in  drag 

dc  i ' ignore ' 

5  in  grow 

dc  i'DoCloseltem' 

6  in  goaway  —  same  as  "Close 

dc  i' ignore' 

7  in  zoom 

dc  i' ignore' 

8  in  info  bar 

dc  i'DoMenu' 

9  in  special  menu  item 

dc  i' ignore' 

■  10  in  OpenNDA 

dc  i' ignore' 

■  11  in  frame 

dc  i* ignore' 

■  in  drop 

CheckFrontW 

Checks  to  see  if  front  window  has  changed  and  if 
so  deals  with  various  menu  enables  and  disables, 
called  by  main  event    loop,    and   activate  events. 


CheckFrontW 


Exitl 
Changed 


Start 

using  MenuData 

using  GlobalData 

PushLong  #0 
_FrontWindow 
PullLong  ThisWindow 

Ida  ThisWindow 
emp  LastWindow 
bne  Changed 
Ida  ThisWindow+2 
emp  LastWindow+2 
bne  Changed 

rts 

anop 

Ida  ThisWindow 
sta  LastWindow 
Ida  ThisWindow+2 
sta  LastWindow+2 

jsr  TypeThisW 

Ida  ThisWType 


;get  the  current  front  window. 

;Check  to  see  if  it  is 
;still  the  same  window  as 
;last  time 


;No  Change  No  problem. .. .Else. 
; LastWindow  :=  ThisWindow 

;set  ThisWType=type  of  the  new  front  win 
;arriving  here,  the  window  has  changed. 


EVENT.ASM  (main  event  loop) 
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cmp  LastWType 
beq  Exitl 

!ok  so  start  changing  menus 


;it's  type  may  not  have  changed. 
;Branch  taken  if  the  latter  is  true. 


Therelsl 


NotSysW 


cmp  #0 

bne  Therelsl 

jsr  SetupForNoW 
bra  FinishUp 


ANOP 

cmp  #1 

bne  NotSysW 

jsr  SetUpForDaW 
bra  FinishUp 

jsr  SetUpForAppW 


!  And  drop  into  exit  stuff 


FinishUp 


ReallyDone 


Ida  NeedToUpdate 
beq  ReallyDone 

_DrawMenuBar 
stz  NeedToUpdate 

Ida  ThisWType 
st a  LastWType 
rts 


;is  there  a  front  window 
;take  this  branch  if  there  is. 

;if  no  front  window  then  disable 
/various  thing  I  care  about  and  go 
; Finish  up 


;is  it  a  system  (Da) 
/taken  if  not. 

;else  it  is  a  da.  do  what's  needed 
;and  do  the  exit  stuff 

;A-reg  -  Wtype.  Go  deal  w/menu  stuff 


;has  the  menu  bar  changed 
;taken  if  not.  else 

;we  need  to  re-draw  the  menu 
;and  say  we  did  it. 


; LastWType  :=  ThisWType 


*  figure  out  the  type  of  the  front  window. 

*  0-  there  is  no  window.  1  =  it's  a  da  window.  2  -  App  Font  Win.  3-  App  Pic  Win. 

TypeThisW 


DoneEarly 
WasApp 


a  nop 
Ida  ThisWindow 
ora  ThisWindow+2 
sta  ThisWType 
beq  DoneEarly 

PushWord  #0 

PushLong  ThisWindow 

_GetSysWFlag 

pla 

beq  WasApp 

Ida  #1 

sta  ThisWType 

rts 

Anop 

PushLong  #0 
PushLong  ThisWindow 

_GetWrefCon 

pla 

sta  Temp 

plx 

stx  Temp+2 

jsr  deref 

sta  0 
stx  2 


;was  there  a  window  at  all  ? 

;if  no  front  window  then  ThisWtype-0 
/taken  if  there  really  was  no  front  win 

;get  and  save  wuther  or  not 

;this  is  a 

/system  window  or  not. 

;0  means  not  a  sys  window 

;it's  a  sys  (da)  window  so 
;set  lastwtype  =  1 


;it's  an  app  win.  find  out  what  kind. 

/space  for  get  ref  con  in  a  sec 
/else  I  have  the  window  ptr 

/get  ref con  it  has  handle  to  data 

/recon  handle  to 
/temp  and  A/X 


/lock  it  down  for  a  sec 


332 


Appendix  E:  HodgePodge  Source  Code:   Assembly  Lanauaae 


ldy  #oFlag 
Ida  tO],y 
beq  PicW 

Ida  #2 

st a  ThisWType 
bra  OuttaHere 

Ida  *3 

sta  ThisWType 


,- check  if  picture 
;get  window  type 


;it's  a  font  window  so. 

; say  so  and 
,■  split 

;it's  a  pic  window,  so 

;  say  so  and  split. 


OuttaHere 


Ida  Temp 
ldx  Temp+2 
jsr  Unlock 
rts 


; unlock   the  refcon  handle. 


Temp 


ds   4 


ThisWindow 
LastWindow 


ds   4 
ds   4 


**************************************************** 


*  doQuitltem 
* 

*  Sets  quit  flag. 
* 

doQuitltem  START 

using  GlobalDATA 


********* 


Ida 

♦  True 

sta 

QuitFlag 

rts 

END 

************************************************** 


*  DoActivate 

*  Handles  activation  of  windows  and  adjusts  the  edit  meun 

*  based  on  window  type. 


DoActivate     Start 

using  GlobalData 

Ida  EventModifiers 
and  fl 
beq  end 


***************** 


*************** 


end 


jsr  CheckFrontW 
rts 

END 


; don't  care  about  deactivate  ? 


EVENT.ASM  (main  event  loop) 


************************** 


******** 


************************ 


*  SetUpForAppW 

*  Sets  the  edit  menu  items  up  for  the  application  window: 

*  that  is  disabling  them.  And  sets  the  other  file  menu  items 

*  accordingly. 


*******  ************************»*»**********< 


SetUpForAppW 


Start 

Using  GlobalData 

Using  MenuData 


************** 


PushLong  #0 
PushWord  ISavelD 

Ida  ThisWType 

cmp  #3 

bne  NoSaveEnable 

PushWord  #True 
bra  Cont 


NoSaveEnable   PushWord  #False 


Cont 


PushWord  ICloseWID 
PushWord  #True 


;get  ready  to  call  changeMitems 
;We  gonna  do  save  item,  but  we  need 

;to  figure  out  whether  it  should  be 
; enabled  or  not.  is  it  a  font  window  ? 
;if  so  dont  enable  the  save  item. 

;else  push  true  for  enable 


SkipPrint 


Exit 


Ida  PrintAvail 
beq  SkipPrint 

PushWord  #PrintID 
PushWord  #True 
PushWord  ISetUpID 
PushWord  #True 
jsr  ChangeMitems 

Ida  LastWType 
cmp  #1 
bne  Exit 

PushWord  #$0080 

PushWord  #EditMenuID 

_SetMenuFlag 

Ida  #True 

sta  NeedToUpdate 

rts 

END 


;was  it  a  da  last  ? 

;if  not  we  don't  need  to  do  whats  next 

/disable  edit  menu 


;set  update  flag  so  I  only  redraw 
;the  menu  bar  once 


************** 


*  SetUpForNoW 


******************* 


A*********************, 


******** 


*  Sets  the  edit  menu  items  up  for  the  desk  ace  window- 
that  is  enabling  edit  menu,  and  close  in  file  menu 

*  accordingly. 


******************** *******,»****************, 
SetUpForNoW    START 

Using  GlobalData 

Using  MenuData 


******************** 


PushLong  #0 
PushWord  #SaveID 
PushWord  #False 


;end  of  list  mark  first... 

;disble  save 

;i  desire  disable. 
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PushWord  JPrintID 

PushWord  IFalse 

PushWord  #SetUpID 

PushWord  #False 

PushWord  fCloseWID 

PushWord  #False 
jsr  ChangeMItems 

Ida  LastWType 
cmp  #1 
bne  Exit 

PushWord  #$0080 

PushWord  #EditMenuID 

_SetMenuFlag 

Ida  #True 

sta  NeedToUpdate 


; enable 


;what  was  it  last 

;was  it  a  da  last  ? 

;if  not  we  don't  need  to  do  whats  next 


; disable  edit  menu 


;set  update  flag  so  I  only  redraw 
;the  menu  bar  once 


Exit 


rts 
End 


********* 


*  SetUpForDaW 

*  Sets  the  edit  menu  items  up  for  the  desk  ace  window: 

*  that  is  enabling  edit  menu,  and  close  in  file  menu. 

*  accordingly. 

* 
****************************************************************** 

SetUpForDaW    START 

Using  GlobalData 
Using  MenuData 


PushLong  #0 
PushWord  (tSavelD 
PushWord  #False 
PushWord  #PrintID 
PushWord  IFalse 
PushWord  #SetUpID 
PushWord  #False 


;end  of  list  mark  first. 

;disble  save 

;i  desire  disable. 


PushWord  tCloseWID 
PushWord  #True 
jsr  ChangeMItems 

Ida  LastWType 
cmp  #1 
beq  Exit 

PushWord  #$ff7f 

PushWord  #EditMenuID 

_SetMenuFlag 

Ida  #True 

sta  NeedToUpdate 


.■enable 


;what  was  it  last 

;was  it  a  da  window  last  ? 

;if  so  we  don't  need  to  do  whats  next 


; enable  edit  menu 


;set  update  flag  so  I  only  redraw 
:the  menu  bar  once 


Exit 


rts 
END 


EVENT.ASM  (main  event  loop) 
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*************************************ttttttt***********ttttt**tttt 

* 

*  ChangeMItems 
* 

*  Enables/Disables  the  various  menu  items  according  to  the 

*  flags  pushed  on  stack. 

* 

*  Entry  Stack  Looks  like: 

0  ;long  indicator  of  end  of  items 

ItemID  ;word  item  id 

Enable/Disable  Flag    ;  (word)  true  =  enable 
* 

ItemID  ;word  item  id 

Enable/Disable  Flag    ; (word)  true  -  enable 

* 

*  Return  ;word 

*  Sp  -> 

***************tttit******************************tttttt*ttt****** 
ChangeMItems   Start 


Lp 


DoEnable 


Done 


PullWord  RtaTemp 

Ida  3,s 

beq  Done 

pla 

bne  DoEnable 

_DisableMItem 
bra  Lp 

_EnableMItem 
bra  Lp 

PullLong 

PushWord  RtaTemp 
rts 


;save  return 

; check  for  end  of  list  mark 
;if  so  split 


;taken  if  we  should  enable  items 

;else  disable  them 
;and  start  over 

/enable  item 
;one  more  time 

;pull  end  of  list  mark 

;push  return  address 


RtaTemp        ds  2 
EnableFlag     ds  2 


END 
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WINDOW.ASM  (windows) 


*************** ***************************************** ********************** 
* 

*        HodgePodge:   An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


ASM65816  Code  file  "WINDOW.ASM"  —  Open/Close  windows 


********************** 


**************************************** 


********************** 


HideAllWindows 

************************************ 


************************* 


HideAllWindows   START 

using  GlobalDATA 


HideLoop 


doHid 


stz  VIndex 

PushLong   #0 

__FrontWindow 

ldx  VIndex 

pla 

sta  VTable,x 

pla 

sta  VTable+2,x 

cmp  #0 

bne  dohid 

Ida  Vtable,x 

bne  dohid 

rts 

pha 

Ida  Vtable,x 

pha 

_HideWindow 

Lda  Vindex 

clc 

adc  #4 

sta  Vindex 

bra  HideLoop 

END 


: index  for  list  of  what  was  vis 
.-hide  'em  all,  looks  neater 


rail  vis.  windows  hidden  now 


WINDOW.ASM   (windows) 


337 


*************************** 


************************************* 


DoOpenltem  : 

1)  Make  sure  not  too  many  windows 

2)  Call  AddToMenu  to  add  Its  name 


open  already  —  may  show  dialog 
into  the  "windows"  menu  list 


***************************** 


DoOpenltem     START 


********* 


************************** 


using  GlobalDATA 
using  FontDATA 


Ida  Windex 

cmp  #LastWind 

boc  OkToOpen 

Jsr  ManyWindDialog 

sec 

Done 

rts 

OkToOpen 

jsr  OpenWindow 

bcs  Done 

jmp  AddToMenu 

;Check  if  too  many  windows  open  already 
;...  otherwise  "window"  menu  overflows! 
;No,  so  go  ahead  and  try  to  open  one 
;Yes,  so  confront  user  with  dialog  box 
;Set  carry  because  it  didn't  happen 


;if  we  didn't  open,  don't  add  it 
;Add  it  to  the  menu  list  and  exit 


***************************************»»,*,***************** 
*  DoSaveitem  : 


************************* 


******************************* 


******** 


DoSaveitem     START 

using  GlobalDATA 
using  IOData 


pushlong  #0 

_FrontWindow 

pla 

sta  whichwindow 

plx 

stx  whichwindow+2 

PUSHLONG  #0 
PUSHLONG  whichwindow 
_GetWrefCon 

pla 
plx 

jsr  deref 

sta  0 

sta  Refptr 

stx  2 

stx  Refptr+2 

ldy  #oFlag 
Ida  [0],y 
beq  oktosav 
rts 


;it's  the  front  window  we're  saving 

;get  result  for  pushing  in  a  sec. 
; space  for  result 
;refcon  has  handle  to  data 


; check  if  picture 

;save  only  type  0  windows 
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oktosav 


PUSHLONG  #0 
PUSHLONG  whichwindow 
GetWTitle 


; space  for  result 


pla 

sta  NamePtr 

plx 

stx  NamePtr+2 


PushWord  #20 
PushWord  #20 
PushLong  #Prompt2 
PushLong  NamePtr 
Pushword  #15 
PushLong  #reply 
SFPutFile 


x  loc 

y  loc 

prompt  string  pointer 

File  name 

Max  file  name  length 

reply  list  result 


Ida  r_good 
bne  Saveitoff 


<>  0  means  OK  to  load  it 


Saveitoff 


anop 
WaitCursor 


Ida  Refptr 
sta  0 

Ida  Refptr+2 
sta  2 


ldy  #oHandle 

Ida    [0],y 

sta  PicHandle 

iny 

iny 

Ida  [0],y 

sta  PicHandle+2 

Ida  PicHandle 
ldx  PicHandle+2 
jsr  DeRef 
sta  PicDestOUT 
stx  PicDestOUT+2 

Ida   #R_fullPN 
sta  NamePtr 
Ida   #AR_FullPN 
sta  NamePtr+2 


this  de-refd,    is  the   data  to  write  oute  pichandle    (we'll   de-allocate) 


now  pointing  to  what   we  write 

put  pointer  to   name   in  i/o  param  block 


Jsr  SaveOne 
Bcs  OuttaHere 

Ida  refptr 

clc 

adc  (oLength 

sta   0 

sta  refptr 

Ida  refptr+2 

adc  #0 

sta  2 

sta  refptr+2 

Ida  r_Fname 
and  #$00FF 
tay 


;  now  fix  up  name 

;  where  the  name  will  go 

;  save  in  0,2  also  for  later  indirect 
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sep  #%00100000 
longa  off 
cpynm         Ida  r_Fname,y 
sta  [0],y 
dey 

bpl  cpynm 
rep  #%00100000 
longa  on 


pushlong  refptr         ; (it  points  to  string  now,  remember?) 
pushlong  whichwindow 
SetWTitle 


Ida  #0 

;  re-calc  size 

pha 

pha 

PushWord  #WindowsMenuId 

CalcMenuSize 

OuttaHere 

Ida  PicHandle 
ldx  PicHandle+2 
jsr  Unlock 

InitCursor 

rts 

refptr 

ds   4 
END 

**************************************************************** 

* 

*  OpenWindow: 

* 

*  1)  Call  SFGETFILE  to  get  name  of  file  to  display  in  window 

*  (or  the  dialog  to  select  font  if  Display  Font  call) 

* 

*  2)  Gets  memory  for,  and  loads  the  picture/font  data  into  memory 

* 

*  3)  Allocates  a  new  window 

*  a)  puts  handle  to  MyWindowInfo  in  WrefCon 

*  b)  note  that  routine  to  draw  picture  contents  is  set  to  "PAINT" 

*  c)  note  for  font  draw  contents  is  "DISPFONTWINDOW" 

* 

*  The  definition  of  MyWindowInfo  is  contained  in  global  data 

* 

*  If  the  menu  manager  is  being  used  to  add  itemlist  items  with  the  file 

*  name,  it  will  squeeze  the  \N  etc.  together  (see  AddToMenu) .   In  any 

*  case,  the  file  name  string  for  the  window  title  can  still  be  found 

*  starting  at  this  area+5 

* 

*  returns:  carry  set  -  didn't  open  it  (user  cancelled  SFGETFILE) 

*  carry  clear  -  window  opened 
* 

**************************************************************** 
OpenWindow     START 

using  GlobalDATA 

using  IOData 

using  FontDATA 

using  WindowData 

Ida  TaskData 

cmp  #ShowFontID  ;  is  it  open  for  font  window? 

bne  AskUser 
jsr  DoChooseFont 
bcs  stp 
jmp  DoTheOpen 
stp  rts  ; cancelled  choose  font 
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call  SFGETFILE  to  request  the  file  name 


HandleError 


Ida  #20 

pha 

Ida  #20 

pha 

PushLong  #Prompt 

PushLong  (OpenFilter 

PushLong  #0 

PushLong  (reply 

_SFGetFile 

Ida  r_good 

bne  loadltup 

sec 

rts 


;  x  loc. 

;  y  loc. 

;  prompt  string  pointer 

;  Do  dimmed  display  of  unloadables 

;  list  of  types  to  include  —  0  for  all 

;  reply  list  result 

;  <>0  means  OK  to  load  it 

;  carry  set  return:  didn't  open 


********* 


*  Get  space  for  the  picture  file 


******** 


LoadltUp 


a  nop 

PushLong  #0 
PushLong  #$8000 
PushWord  MylD 
PushWord  #$0000 
PushLong  #0 
NewHandle 


;  space 

;  size 

;  id 

;  no  restrictions 

;  loc  not   important 


DoTheOpen 


pla 

sta  PicHandle 

plx 

stx  PicHandle+2 

bcs  HandleError 

jsr  Deref 

sta  PicDestIN 
stx  PicDestIN+2 

a  nop 

PushLong  #0 
PushLong  JMyWinfoSize 
PushWord  MylD 
PushWord  #$C000 
PushLong  #0 
NewHandle 


;  if  error  occured  from  no  handle 

;  deref ence  handle  (in  a,x) 

;  put  pointer  in  i/o  param  block 


;  space 

;  size 

;  id 

;  fixed  and  locked 

;  loc  not  important 


pla 

sta  refcon 

plx 

stx  refcon+2 

bcs  HandleError 

jsr  deref 

sta  refptr 
sta  0 

stx  refptr +2 
stx  2 


;de  ref.  for  storing  stuff  into 
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********* 


Start  by  assuming  this  will  be  a  picture  window  (not  a  font  window) . 
We  set  the  address  of  the  drawing  routine  to  PAINT  and  set  the  flag 
in  MyWindowInfo  record  to  0  indicating  picture. 


********* 


Ida  #Paint 
sta  DrawRtn 
Ida  (TPaint 
sta  DrawRtn+2 
ldy  #oFlag 
Ida  #0 
sta  [0],y 


;  first  the  address  of  the  Paint 
;  routine 


;  Now  set  the  flag  field 


Now  we  see  if  that  silly  assumption  above  was  correct. 


Ida  TaskData 
cmp  #ShowFontID 
bne  set 10 


look  at  the  menu  item  that 

brought  us  here. 

not  the  font  one  so  go  on 


Ida  #1 

ora  MonoFlag 

sta    [0],y 

Ida  DesiredFont 

sta  PicHandle 

Ida  DesiredFont+2 

sta  PicHandle+2 


fix  the  flag  field 
set  bit  1  if  monospaced  font 
(y  still  set) 

put  the  chosen  fontid  where 
we  will  later  put  it  in 
the  MyWindowInfo  record 


Ida  #DispFont Window 

sta  DrawRtn 

Ida  #ADispFontWlndow 

sta  DrawRtn+2 

jmp  DoMovNam 


finally,  fix  the  pointer  to  the 
drawing  routine 


Ida  #R_fullPN 
sta  NamePtr 
Ida  #~R_FullPN 
sta  NamePtr+2 


put  pointer  to  name  in  i/o  param  block 


********* 


*  load  picture  in  "NamePtr"  into  "PicDest" 


********* 


jsr  LoadOne 
bcc  DoMovNam 


load  it 


lOError        anop 

PushLong  RefCon 

_DisposeHandle 

PushLong  PicHandle 

_DisposeHandle 

sec 

rts 


There  was  an  error  loading  the  file 
so  dispose  of  the  memory  that  we 
allocated  while  trying  to  create 
this  window 
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********** 


Move  the  files  name  into  the  param  block 


Ida  refptr 
sta  0 

Ida  refptr+2 
sta  2 

Ida  pichandle 

ldy  #oHandle 

sta    [0],y 

iny 

iny 

Ida  pichandle+2 

sta  [0],y 

ldy  #oBlank 
Ida  #'   ' 
sta  [0],y 


;use  zero  page  for  indirect  stores 


:into  the  reef on  area  (refptr) 


Put  blank  in  record  at  blank  field 
(note  this  16  bit  store  will  over- 
write the  length  field  but  we  don't 
care  since  we  fix  it  below. 


Ida  refptr 

clc 

adc  JoLength 

sta  windaddr 

sta  0 

Ida  refptr+2 

adc  #0 

sta  windaddr+2 

sta  2 


;  where  the  name  will  go 

;  save  in  0,2  also  for  later  indirect 


Ida  r_Fname 

and  #$00FF 

emp  #MaxNameSize 

bmi  NameLenOK 

Ida  #MaxNameSize 

sep  #%00100000 

sta  r_Fname 

rep  #%00100000 

tay 

Sep  #%00100000 

longa  off 

Ida  r_Fname,y 

sta  [0],y 

dey 

bpl  cpynm 

rep  #%00100000 

longa  on 

ldy  #350 

ldx  #640 

stx  DataWidth 

stx  mew 

sty  IsizPos+6 


;adjust  max  siz 

; adjust  pixel  count 


Set  up  the  DataHeight  based  on  the  type  of  window  it  is. 


Ida  #188 

sta  DataHeight 

Ida  RefPtr 

sta  0 

Ida  RefPtr+2 

sta  2 


assume  picture  and  make  200  the  max 

height 

now  see  what  it  really  is 


WINDOW.ASM   (windows) 


343 


Ida  TaskData 
cmp  #OpenWID 
bne  NotisPicture 
jmp  IsPicture 


NotisPicture 


PushLong  OrigPort 
Set Port 


PushLong   #0 
GetFontID 


Use  the  original  port  obtained  during 
startup  to  make  sure  a  port   is  set 
for  the  following  text  size  calcs 

save  this  on  the  stack 


ldy  #oFontID+2 
Ida    [0],y 
pha 
dey 
dey 

Ida    [0J,y 
pha 

PushWord  #0 
InstallFont 


now  install  the  font  that  will 
be  used  in  the  current  port 


PushLong  #FIRecord 
_GetFontInfo 

PushLong  #0 

Ida  ascent 

clc 

adc  Descent 

pha 

PushWord  #NumLines+2 

_Multiply 

pla 

sta  DataHeight 

pla 

jsr  FindMaxWldth 


get  the  font  info  so  can  get 
ascent  and  descent. 

space  for  result 

now  multiply  sum  of  ascent  & 

descent  by  num  lines  to  draw 


put  result  in  DataHeight 
strip  off  high  word  of  nothing 


IsPicture 

********* 


PushWord  #0 
InstallFont 


anop 


using  saved  fontid  on  stack 
re-install  the  orig  font 


*  offset  upperleft  corner  for  opening  of  window 


********* 


MovOff 


ldx  #0 

Ida  ISizPos,x 

clc 

adc  Wyoffset 

sta  SizPos,x 

Ida  ISizPos+2,x 

clc 

adc  Wxoffset 

sta  SizPos+2,x 

inx 

inx 

inx 

inx 

cpx  #8 

bne  MovOff 


Ida  WxOffSet 

clc 

adc  #20 

sta  WxOffset 

Ida  WyOffset 


; adjust  offsets 
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doYset 


clc 

adc  #12 
cmp  #120 
bne  DoYset 
Ida  #12 
sta  WyOffset 


;lf  we  get  too  low,  start  at  top 


********** 


*  Now,  Finally,  create  the  new  window 


********** 


Finally       PushLong  #0  ;  space  for  result 

pushlong  #WindowParamBlock 
NewWindow 


pla 

sta  whichwindow 

pla 

sta  whichwindow+2 

PushLong  OrigPort 
_SetPort 

Ida  PicHandle 
ldx  PicHandle+2 
jsr  Unlock 


Use  the  original  port  obtained  during 
startup  to  make  sure  a  port  is  set 

unlock  handle 


*  Force  origin  boundaries  (see  Manual  definition  of  Window  Mgr's  SetOriginMask) 


PushWord  #SFFFE 
PushLong  whichwindow 
_SetOriginMask 

clc 
rts 
end 


carry  clear  return:  we  opened  it 


************************************************************* 


WindowData 


******************* 


*******************> 


********* 


WindowData  data 

WindowParamBlock   anop 

dc  12'WindowEnd' 

dc  i2'FTitle+FC 

dc  14' 0" 

dc  14'0' 

dc  12'0, 0,0,0' 

dc  14 "0' 

dc  i2'0' 

dc   12' 0' 

dc  12 '200' 

dc   12 "640' 

dc  12' 200' 

dc   12 '640' 

dc  12'4' 

dc  12'16' 

dc  i2'40' 


windaddr 
refcon 


DataHeight 
DataWidth 

McW 


WindowParamBlock ' 

lose+FRScroll+FBScroll+FGrow+FZoom+FMove+FVis' 
Ptr  to  title 
RefCon 

Full  Size  (0=  default) 
Color  Table  Pointer 
Vertical  origin 
Horizontal  origin 
Data  Area  Height 
Data  Area  Width 
Max  Cont  Height 
Max  Cont  Width 

Number  of  pixels  to  scroll  vertically. 
Number  of  pixels  to  scroll  horizontally. 
Number  of  pixels  to  page  vertically. 
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DrawRtn 
SlzPos 


WindowEnd 

Refptr 
ISizPos 


FiRecord 

Ascent 

Descent 

Leading 

WidMax 


dc  i2'160' 

dc  14' 0" 

dc  i2'0' 

dc  14' 0' 

dc  i4'0' 

dc  14 'Paint' 

d<=  12'  0,0, 0,0' 

dc  i4'$FFFFFFFF' 

dc  14'0' 

anop 


ds 
dc 


anop 
ds  2 
ds  2 
ds  2 
ds  2 


'20,10,80,350' 


Info  bar  height 

DefProc. 

Routine  to  draw  info,  bar 

Routine  to  draw  content   ' 

Size/pos  of  content 

Plane  to  put  window  up  in 

Address  for  window  record' (0  to  allocate, 

;refcon  pointer  to  20  bytes 
;Size/pos  of  content 


*********** 


END 


********** 


******** 


*  OpenFilter 


****************.****,**»„llt)ktil](44 


*   St"  ^^Ll^V:   SFGetFUe  t0  *"~  •*  the  fiietyPes 
t*  On  entry,  the  stack  looks  like  this: 

previous  contents      ( 

!?!!!.!!!  res"1_t"         i   «°rd 

_^inter_toj_lrec£^-~t--  J  long 
f«^n_addre"s"s"       J  3  bytes 


********** 


OpenFilter 


*********, 


********** 


<-  SP 


********** 
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start 

using  GlobalData 

phb 

phk 

plb 

pla 

sta  RtnAddr 

Pla 

sta  RtnAddr+2 

tdc 

sta  DPSave 

Ida  MyZP 

ted 

pla 
sta  0 
pla 
sta  2 

ldx  #1 

Idy  #$io 


;  sTDBRBRb(r  evenoutRTLad^> 

'  set  DBR  back  to  this  bank 
;  save  the  return  address 


;  save  the  ROM's  ZP 
;  and  swap  in  ours 


i    airectory  entry 


assume  visible  and  dimmed 
look  at  the  filetype  byte 
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Ida 

[0],Y 

and 

l$0OFF 

cmp 

#$cl 

bne 

NotPicFile 

ldx 

#2 

NotPi 

BFile 

txa 

sta 

l,s 

Ida 

DP Save 

ted 

Ida 

RtnAddr+2 

pha 

Ida 

RtnAddr 

pha 

plb 

;    don't    look  at  the  entire  word 


pass  on  all  others 

show  it  as  a  selectable  entry 


;  pass   it  back  on  the  stack 

;  point  back  to  the  old  DP 

;  and  put  the  return  address  back 

;  restore  old  DBR 


DPSave 
RtnAddr 


ds  2 
ds  4 


end 

*************************************************************** 

FindMaxWidth  -  this  routine  finds  out  how  wide  the  window 
should  be  for  the  currently  installed  font. 

*************************************************************** 


FindMaxWidth 


LineLoop 


start 

using  WindowData 
using  FontData 
using  GlobalData 

PushWord   #0 
_GetFontFlags 

ldy  #oFlag 
Ida    [01, y 
lsr  a 
and  #$0001 

pha 

_SetFontFlags 

stz  MaxSoFar 

Ida  #1 

sta  LineCounter 

anop 

PushWord  #0 

phk 

phk 

pi  a 

and  IS00FF 

pha 

Ida  LineCounter 

asl  a 

tax 

Ida  LineTable,x 

pha 

_StringWidth 


save  prev  set  mono/pro  flag 


keep  the  result  on  the  stack  while 
we  set  it  to  what  we  want  (as 
defined  by  its  window  type  set  up 
when  we  open  this  window) 


;  space  for  width  result. 

;  Get  a  pointer  to  the  current  line. 

;  The  upper  word  is  the  same  as  the 

;  program  bank. 


;  The  lower  word  is  stored  in  a  table. 
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LessThan 


LineCounter 
MaxSoFar 


pla 

cmp  MaxSoFar 
bcc  LessThan 
sta  MaxSoFar 

a  nop 

inc  LineCounter 
Ida  LineCounter 
cmp  #NumLines 
bcc  LineLoop 

Ida  MaxSoFar 

clc 

adc  #10 

sta  DataWidth 

_SetFontFlags 

rts 
ds  2 
ds  2 

end 


How  does  this  line  compare  with  the 
previous  longest  line? 

>  or  =,  so  save  it  as  record  holder, 
bump  current  line 


Get  the  width  of  longest  line. 

Add  in  room  for  left  and  right  margins 


restore  old  settings 


DoCloseltem 

Close  a  window,  and  dispose  of  extra  data  (in  WrefCon) 

and  remove  it  from  window  list.   If  no  windows,  then  dim  "Window" 

menu  and  disallow  printing. 


DoCloseltem 


Got  It 


TherelsOne 


:***.*.****•  *  *** 

START 

using  GlobalDATA 

pushlong  #0 

_Front Window 

pla 

sta  whichwindow 

pla 

sta  whichwindow+2 

ora  Whichwindow 

bne  TherelsOne 

rts 

PushLong  Whichwindow 
_CloseNDAByWinPtr 
bcc  Gotlt 


****************** 


********** 


;  Must  be  one  of  mine, 
dothecls       PUSHLONG  #0 

PUSHLONG  whichwindow 

_GetWrefCon 

pla 

sta  temp2Handle 

plx 

stx  Temp2Handle+2 

jsr  deref 
sta  0 
stx  2 

ldy  (toHandle 
Ida  [0],y 
sta  PicHandle 
iny 

iny 


,-it's  the  front  window  we're  deleting 
;...so  get  its  GrafPortPtr 


get  result  for  pushing  in  a  sec. 
was  there  one? 

quit  now 

if  it  is  a  system  window,  this  will 

close  it 

no  error  so  done 


; space  for  result 

;refcon  has  handle  to  data 

;the  refcon  to  de-allocate 
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Ida  [0],y 

sta  PicHandle+2 

ldy  #oFlag 
Ida  [0],y 
beq  itsapic 
stz  PicHandle 
stz  PicHandle+2 


;  the  pichandle  (we'll  de-allocate) 
;  check  if  picture  or  font 

,-  flag  so  we  don't  dispose 


jsr  AdjWind 

clc 

adc  #300 

sta   IDdelete 

Ida  windex 

cmp  #1 

bne  MoreThanOne 

pushlong  lorigitem 

pushword  #0 

pushword  #WindowsMenuID 

_InsertMItem 

Pushword  #$0080 
PushWord  #WindowsMenuID 
_SetMenuFlag 

Lda  #True 

Sta  NeedToUpdate 

stz  PrintAvail 


Ida 

#20 

sta 

WxOffset 

Ida 

#12 

sta 

WyOffSet 

Ida 

IDdelete 

pha 

DeleteMItem 

dec 

windex 

Ida 

windex 

beq 

nomore 

sta 

IdCounter 

Ida 

#300 

sta 

IDstart 

sta 

IDNew 

Ida 

IdStart 

cmp 

IdDelete 

bne 

Dolt 

inc 

Idstart 

bra 

back 

pushword  IdNew 

pushword  IdStart 

_SetMItemId 

inc 

IdStart 

inc 

IdNew 

dec 

IdCounter 

bne 

back 

Ida 

•  0 

pha 

;  goes  and  pulls  window  from  WindowList 

;  position  returned  in  a-reg. 

;  start  at  300 

;  the  MenuID  to  de-allocate 

;  if  only  one,  we  must  be  special 


r  We're  now  deleting  the  only  window 

;    left. 

*  add  old  "no  windows"  menu  item. 
^Disable  windows  menu 


Disallow  printing 

reset  start  loc  for  window  sizing 


;now  delete  this  item  from  menus 


;now,  renumber  list 

;  none  left,  skip 

;  counts  how  many 

;  always  the  starting  no. 

;  will  be  first 

;  and  the  new  one 

;  is  it  the  one  we  deleted? 

;  nope,  go  re-set  ID 

;  yes,  skip  over  it 


;    re-calc   size 
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pha 

PushWord  #WindowsMenuID 

_CalcMenuSize 

Pushlong  Temp2Handle 
_DisposeHandle 


Ida  PicHandle 
bne  dodisp 
Ida  PicHandle+2 
beq  skipdisp 

DoDisp         Pushlong  PicHandle 
_DisposeHandle 

SkipDisp      PushLong  WhichWindow 
_CloseWindow 


;get  rid  of  refcon  area 
;ls  it  font 

;get  rid  of  picture  area 
;get  rid  of  window 


skip  rts 

***********  *************»„  tll 

* 

*  ^WhichWindow"  "h  d6teteS  !  Wlnd°W  USt  ltem  Which  -tch- 
^     WhichWindow'  and  returns  in  a-reg.  where  it's  position  was 

*  Note:  it's  optimized  to  find  things  near  end  of  list 

(if  you'd  prefer  the  other  end,  you'd  need  some  different  logic 
but  here,  generally,  you'll  open,  look  at  it,  and  close  it  so' 
this  method  seems  best)  ' 


;use  this  to  count  thru 

;  pt.  before  last  for  end  (a-2) *4 


********, 

t****************,^* 

AdjWind 

Ida  Windex 

tay 

dec  a 

asl  a 

asl  a 

sta  IDCounter 

adjloop 

dey 

bmi  AdjDone 

tya 

asl  a 

asl  a 

tax 

Ida  WindowList,x 

anp  WhlchWindow 

bne  adjloop 

Ida  WindowList+2,x 

anp  WhichWindow+2 

beq  ShoveChk 

bra  Adjloop 

Shovelt 

Ida  WindowList+4,x 

sta  WindowList,x 

Ida  WindowList+6,x 

sta  WindowList+2,x 

inx 

inx 

inx 

inx 

ShoveChk 

cpx  IdCounter 

bne  shovelt 

AdjDone 

tya 

rts 

IdNew 

ds  2 

IdStart 

ds  2 

IdCounter 

ds  2 

IDdelete 

ds  2 

END 

,-get  the  pointer  (uniqueness  exists) 


rnow  shove  things  up 
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***************** 


*********** 


Paint 

This  draws  picture   in  the  window  when  task  master  calls. 


********************************* 
Paint  START 

using  GlobalData 
********** 


**************** 


*  get  my  own  zero  page 


phb 

phk 

plb 

phd 

Ida  MyZP 

ted 

********** 


get  the  correct  window  port  (got  here  from  within  taskmaster) 


pushlong  #0 

GetPort 

plx 

ply 

PUSHLONG  #0 

phy 

phx 

_GetWrefCon 

pla 

sta 

Temphandle 

plx 

stx 

TempHandle+2 

jsr 

Deref 

sta 

0 

stx 

2 

ldy 

#oHandle 

Ida 

[0],y 

sta 

picptr 

pha 

iny 

iny 

Ida 

[0],y 

sta 

picptr+2 

tax 

pla 

jsl 

Paintlt 

Ida  TempHandle 
ldx  TempHandle+2 
jsr  Unlock 

pld 
plb 

rtl 
END 


;get  result  for  pushing  in  a  sec. 

; space  for  result 

;  saved  the  port  here 
;refcon  has  handle  to  data 


dereference 


get  handle  to  pic  data 
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* 

*  Paintlt 

*  The  routine  which  actually  does  the  painting  when  passed  the 

*  the  handle  to  the  picture  in  the  a  S  x  registers. 

* 

**************************************************************** 
Paintlt        START 

using  GlobalData 


;  save  this  on  stack 
;deref.  picture  handle 


y 

copy 


phx 
pha 

jsr  deref 
sta  picptr 
stx  picptr+2 

PushLong  ISrcLocInfo 
PushLong  #SrcRect 
PushWord  #0 
PushWord  #0 
PushWord  #0 
_PPToPort 

pla 

plx 

jsr  Unlock 

rtl 


END 
****************************** ********************************** 

»  DoGoAway  —  not  necessary  because  we  handle  it  the  same  as 
*  DoCloseltem. 


******** 


fr*****************************,^^^^ 


***************** 


«**«*t»«*m».«»«»H1»,tl,irn*»mn<.nt»nm».»t«tii»t 
* 

*  DoWindow 

* 

*  Selects  and  shows  window  in  response  to  menu  selection. 

* 

********************************  ************************  ****„»»ll 
DoWindow       START 

using  GlobalDATA 

PUSHLONG  WHICHWINDOW     ;  select  first  so  it  only  redraws 
_SelectWindow  ;  once 

PUSHLONG  WHICHWINDOW 
_ShowWindow 

rts 


END 
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DIALOG.ASM  (dialog  boxes) 


************************************************** 


************ 


Hodgepodge:   An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


*   ASM65816  Code  file  "DIALOG.ASM"  —  Various  dialogs  taking  modal  control   * 


********************** 


************************************** 


************* * 


********** 


*******  *** 


*  ManyWindDialog  —  Warning  that  too  many  windows  are  open. 


********** 


********************************* 


ManyWindDialog  START 

using  GlobalData 


pha 

pushlong  #OurAlert 

pushlong  #$0000 

_CautionAlert 

pla 

get  the  item  hit 

rts 

OurAlert 

dc 

i'30,120,80,520' 

bounds  rect 

dc 

i'2374' 

id 

do 

h'SO" 

dc 

h'80" 

dc 

h'80' 

dc 

h'80' 

dc 

14 'iteml' 

dc 

i4'item2' 

dc 

i4'0000' 

iteml 

dc 

i2'l' 

id 

dc 

i2'25,320,00,00' 

bounds  rect   for  button 

dc 

i2'ButtonItem' 

type 

dc 

14 'Butl' 

item  descreptor 

dc 

12 '00' 

item  value 

dc 

12'0' 

item  flag 

dc 

14  '0' 

item  color 

item2 

dc 

12'1348' 

id 

dc 

12'11,72,200,640' 

bounds  rect   for  message 

dc 

12'StatText+$8000' 

type  +  disabled 

dc 

14 'Msg • 

item  descreptor 

dc 

12 '00' 

item  value 

dc 

12 '0' 

item   flag 

dc 

14 '0' 

item  color 

Butl 

str    'OK' 

Msg. 

str    'No  more  windows,    pie. 

ise.  ' 

end 
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******************* 


************ ****** 


*************** 


DoAboutltem 


Brings  up  about  box  and  waits  until  button  press  until 

it  puts  it  away.  Shows  how  to  build  a  dialog  window  by  hand. 


DoAboutltem 


ok 


Copy640 

FixDBox 
JoinRect 


******************** 

START 

using  globalData 

PushLong  #0 

PushLong  #34*16+8 

PushWord  Myld 

PushWord  #0 

PushLong  #0 

_NewHandle 

pla 

plx 

bcc  ok 

Ida  #$81 

ldx  #1 

jmp  CheckDiskError 


anop 

sta  ApplelconH 

stx  ApplelconH+2 

jsr  deref 

sta  0 
stx  2 

ldy  #0 

Ida  Applelcon640,y 

sta  [0),y 

iny 

iny 

cpy  #34*16+8 

bne  Copy 640 

ldx  #320-180 
Ida  #320+180 

stx  DRect+2 
sta  DRect+6 

PushLong  #0 
PushLong  #DRect 
PushWord  #True 
PushLong  #0 
_NewModalDialog 

pla 

sta  MDialogPtr 

pla 

sta  MDialogPtr+2 

PushLong  MDialogPtr 
PushWord  #1 
PushLong  #ButtonRect 
PushWord  #ButtonItem 
PushLong  #ButtonText 


;  get  space  for  Icon 

;  #lines  *  bytes/line  +  rect 

;  don't  care  where  it  goes 


out  of  memory 

Go  and  tell  user  error  message, 
and  use  its  RTS  to  exit  from  here. 


;move  Icon  to  new  space 


output 

visible 

refcon 
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PushWord  #0 
PushWord  #0 
PushLong  #0 
_NewDItem 

PushLong  MDialogPtr 

PushWord  #2 

PushLong  #AppleIconRect 

PushWord  Hconltem+ItemDisable 

PushLong  ApplelconH 

PushWord  #0 

PushWord  #0 

PushLong  #0 

_NewDItem 

PushLong  MDialogPtr 
PushWord  #4 
PushLong  #TextRect 

PushWord  #LongStatText2+ItemDisable 
PushLong  IStartOfText 
PushWord  #EndOfText-StartOfText 
PushWord  #0 
PushLong  #0 
NewDItem 


DoModal        PushWord  #0 
PushLong  #0 
_ModalDialog 
pla 

PushLong  MDialogPtr 
_CloseDialog 

PushLong  ApplelconH 
_DisposeHandle 


result 

no  filterproc 

chuck  the  item  hit 


DRect 


rts 

do   i'20, 10,192, 320-10' 


ApplelconH  ds  4 

ApplelconRect     do   i1 135,  20,  0,  0' 


Applelcon640 


anop 

dc   i,0,0,34,64' 
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Text  Re  ct 
StartOfText 


dc 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 

DC 


h  OFFFFFFFFFFFFFFFFFFFFFFFFFFFTFFO ■ 

h  ofoffffffffffffffffffffffffffofo ■ 

*  °F°FFFFFFFFFFFFFFFFFF88FFFFFF0F0^ 
h  '^FFFFFFFFFFFFFFFFSeSSFFSFO' 
h  nL°^FFFFFFFFFFFFF88888FFFFFF0F0  ■ 
h   0F0FFFFFFFFFFFFFF88888FFFFFFF0FO. 

*  ^FFFFFFFFFFFFFSSeSSSFrFSFS- 
hfOFFFFFFFFFFFFFSSSSSFFFFFTFTuFO. 

*  °F°FFFFFFFFFFFFF8888FFFFFFFIF0F0■ 
^  °F°FFFFFF8888FFF88FF8888fSf0. 
^' 0F°FFFF88888888FFF88888888FFF0F0 • 

h-  ofSff^!       eeeeeeeeeeeeeFFFF0F° ' 

h  ■  OFo/wtt eeeeeeeeeee^eeeeFFFFF0F0  • 
k  . «™ FFeeeeeeeeeeeeeeeeeeFFFFFF0FO  ' 
*  °F0FF666666666666666666FFFF™■ 
^  °F°FF666666666666666666FFFFfTofo. 
h  OF0FF666666666666666666FFFFFFOFO • 
h-0F0FF4444444444444444444FFFFF0FS. 
^' OFOFF4«44444444444444444™fO  • 
h"0F0FFF444444444444444444444FFOFn. 

{KSHSKBkEE: 

rpsssKsasE 

{;5SS5!ggSS!figgj-»5: 

hOFOFFFFFFFllllFFFFFllUFFFFFFOFO. 
h   OFOFF FFFFFFFFFFFFFFFFFFFFFFFFOFO • 

h   °FFFFFFFFFFFFFFFFFFFFFFFFFFFFfTo  ■ 


center 
Outline 


EndOfText 


dc  12-4,10,135, 340' 
anop 

dc  h'01',C'J',i'i. 

dc  h'OV,c.s-,i.$ooo8. 

dc  c 'Hodgepodge ',h'0D • 

dc  h'01',c'S',i'$0000'  .    _,„„ 

dc  e  a  potpourri  of  routines  ttat   ^ 

c  trAStfate  many  featu«*  of   • 

c  the  Apple   IIGS  Tools    ' 

h'OD' 

h'OD' 

ddo  h-'oV  APPlS  IIGS  O-vlop-,.*  team  including: 
'-  h'OD' 

'E. 

S. 
h'OD' 
CD. 
c'P. 
h'OD' 

B.  Marks,  D.  Oliver, 

and  K.  Rollin  ' 
h'OD' 
h'OD' 

ddcc  c-'SSSr Apple  Coraputer' 

dc  h'OD' 

dl  cC:^n0Rights,R«erved',h'0D. 

dc  CiSysDate' 
anop 


dc 
dc 
dc 
dc 


dc 

dc 

dc 

dc 

dc 

dc 

dc 

dc 

dc 

dc 

dc 


Berns,  A.  Cabral, 
Glass, • 


C  Ewy, 


Hitchens,  B. 
McDonald, • 


Koning,  s.  Lee, 


G.  Ortiz, 


Inc. 
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ButtonRect  dc   i1 153,  205,  0,0' 

ButtonText  str   'OK' 

MDialogPtr  ds  4 

END 
*************************************************************** 

ShowPleaseWait   /  HidePleaseWait 

Brings  up  a  window  and  immediately  puts  message  in  it 
(without  waiting  for  update  event) . 

*************************************************************** 


ShowPleaseWait   START 

using  globalData 

PushLong  #0 
GetPort 


save  the  current  port 


pla 

st a  SavePort 

pla 

sta  SavePort+2 

PushLong  #0 

PushLong  #DialogTemplate 

_GetNewModalDialog 

pla 

sta  MsgWinPtr 

pla 

sta  MsgWinPtr+2 

PushLong  MsgWinPtr 
_BeginUpdate 

PushLong  MsgWinPtr 
_DrawDialog 

PushLong  MsgWinPtr 
_EndUpdate 

rts 

HidePleaseWait  ENTRY 

PushLong  MsgWinPtr 
_CloseDialog 


begin  the  updating  process 


;  hide  the  window 


PushLong  SavePort 

;  restore  the 

_SetPort 

rts 

MsgWinPtr 

ds  4 

DialogTemplate 

anop 

dc  i'30,120,80,520' 

;  bounding  box 

dc  i'True' 

;  visible 

dc  14' 0" 

;  refcon 

dc  i4'iteml' 

dc  14 -0000' 
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iteml 


Msg 


anop 

dc   12' 1348' 

dc   12'19,70,200,640' 

dc  i2'StatTGXf 

dc   14' Msg' 

dc  12 '00' 

dc   12' 0' 

dc   14 '0' 

str  "Please  wait  while  we 


Id 

bounds  rect  for  text 
type 

item  descreptor 
item  value 
item  flag 
item  color 
set  things  up. ' 


END 


************************* 


*************** 


*  MountBootDisk 

*  This  is  a  routine  that  is  called  whenever  the  application 

*  needs  to  get  something  off  the  boot  volume  and  the 

*  boot  volume  is  not  on  line. 

* 

*  This  can  occur  when  loading  fonts,  tools  or  drivers. 

* 
**************************************************************** 

MountBootDisk  START 

_Set_Prefix  SetPrefixParams 
Get  Prefix  GetPref ixParams 


PushWord  #0 

; Space  for  result 

PushWord  #174 

;x  pos 

PushWord  #30 

;y  pos 

PushLong  #PromptStr 

; Prompt  string 

PushLong  #VolStr 

;Vol  string 

PushLong  #0KStr 

PushLong  #CancelStr 

JTLMount Volume 

pla 

rts 

Prompt Str 

str  'Please  insert  the 

disk' 

OKStr 

str  'OK' 

CancelStr 

str  'Shutdown' 

GetPref ixParams  dc  i'7' 

dc  14'VolStr' 


SetPrefixParams  dc  i'7' 

dc   14'BootStr' 


Vol Str 
Boot Str 


ds   16 
str    '*/' 

END 
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**************************************************************** 

*  CheckToolError 
* 

*  Cause  system  death   if  A  register  is  nonzero  and  carry   set; 

*  otherwise,    it    just   returns. 

* 

*  Error  code  to  make  part  of  string  is  in  A  register. 

*  "Where"  number  to  make  part  of  string  is  in  X  register. 

* 
**************************************************************** 


CheckToolError 

START 

bcs 

RealDeath 

rts 

RealDeath 

pha 

pea 

0 

pea 

0 

phx 

_Hexit 

pla 

sta 

codes 

pla 

sta 

codes+2 

;If  a  tool  error  didn't  happen 
;then  Just  return 

; Save  error  code  for  now 

/Convert  the  "Where"  debug  trace 
/number  to  a  four-digit  ASCII  hex 
/string. 


pla 

pha 

PushLong  IDeathMsg 

_SysFailMgr 


/Restore  error  code 

/Exit  to   system  failure  handler 
/ (bouncing  apple) 


DeathMsg  anop 

dc   il'EndMsg-StartMsg' 
StartMsg  dc  c'    At   $' 

Codes  ds  4 

dc  c'z   Could  not  handle  error  $' 
EndMsg  anop 

END 


**************************************************************** 
* 

*  CheckDiskError  —  Display  stop  alert  dialog  if  ProDOS  error  happened. 
We  sniff  the  A  register  to  see  if  an  error  occurred, 
and  assume  the  X  register  to  be  loaded  with  a 
"where"  value,  used  to  locate  bugs. 


************* 


************************************************** 


CheckDiskError  START 

using  GlobalData 

phx 
pha 

_InitCursor 

pla 
pha 

PushLong  #OurErrStr 
PushWord  #4 
Int2Hex 


;  Save  the  Where  value 

;  Save  the  error  number 

/  Set  pointer — looks  better  than  watch 

/  Restore  the  error  number 

;  Convert  the  error  message 

/  to  an  ASCII  string  4  chars  long 
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pla 
pha 

PushLong  #OurWhereStr 
PushWord  #2 
Int2Hex 


Do  this  just  for  clarity  (note  that 
Where  value  is  already  on  stack ! ) 
Convert  the  Where  value 
to  an  ASCII  string  2  chars  long 


pha 

pushlong  #OurAlert 

pushlong  #$0000 

_StopAlert 

pla 

sec 

rts 


Space  for  result 

Pointer  to  template 

Standard  Filter  procedure 

Draw  box  and  wait  for  mouse  OK  press 

Get  the  item  hit  (the  OK  button) 

Set  the  error  flag 
Return  to  caller 


OurAlert      dc  i1 30, 120,80, 520' 
dc  i'6666' 
dc  h'80' 
dc  h^O* 
dc  h'80' 
dc  h'80' 
dc  14'OKButton' 
dc  14'Message' 
dc  14 '0000' 


bounds  rect 
id 


dc  12 >1' 

dc  12-25,320,00, 00' 

dc  12'ButtonItem' 

dc  i4,OKName' 

dc  12' 00' 

dc  12 '0' 

dc  14 '0' 


id 

bounds  rect  for  button 

type 

item  descreptor 

item  value 

item  flag 

item  color 


Message 

ErrMsgPtr 


dc  12'1348' 

dc  lZ'll^^OO^O' 

dc  i2'StatText+$8000' 

dc  14,Msg' 

dc  12' 00- 

dc  12,01 

dc  14' 0' 


id 

bounds  rect  for  static  text 

type  +  disable  flag 

item  descreptor 

item  value 

item  flag 

item  color 


OKName 

str  'OK' 

Msg 

dc  11 • EndMsg-StartMsg 

StartMsg 

dc  c'Disk  error  $' 

Our Err St r 

ds  4 

dc  c'  occurred  at  $' 

OurWhereStr 

ds  2 

dc  c' . ' 

dc  h'OD' 

EndMsg 

a  nop 
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FONT.ASM  (fonts) 


*********************************************************** 

Hodgepodge:   An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


*  ASM65816  Code  file  "FONT.ASM"  —  Choose  font;  display  font  window  contents  * 


******** 


******** 


******** 


************************************************************* 


FontData 


********************* 
FontDATA      DATA 


t* ******** 


*********************** 


FontWinPtr     ds  4 

DesiredFont  dc  14  ■  $0800FFFE' 

MonoFlag  dc   12'  0' 

CurFontlnfo  anop 

CFAscent  ds   2 

CFDescent  ds   2 

CFMaxWid  ds   2 

CFLeading  ds  2 


;    System  Font   size   8 

;    start   out   showing  proportional 


CurHeight  ds  2 

LineCounter  ds   2 

CurPos  ds   4 


NumLines  equ  13 

LineTable  dc   i'LineO, Linel,Line2,Line3,  Line4 ' 

dc   i'Line5,Line6, Line7, Line8,Line9' 
dc   i,LinelO,Linell,Linel2,Linel2,Linel2' 


LineO     ds  30  ;   max  name   len  is  25   +   1   for   length 

''  ;    and  4    for  size   info 

Linel     str    '  ' 

Line2  str  'The  quick  brown  fox  jumped  over  the  lazy  dog.' 

Line3  str  'She  sells  sea  shells  down  by  the  sea  shore.' 

Line4  str  ' ' 

Llne5    dc  h'20' 

dc  h'00  01  02  03  04  05  05  07  08  09  0A  0B  0C  0D  0E  OF' 

dc  h'10  11  12  13  14  15  16  17  18  19  1A  IB  1C  ID  IE  IF' 
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Line6  dc  h'20' 

dc  h'20  21  22  23  24  25  26  27  28  29  2A  2B  2C  2D  2E  2F- 

dc  h'30  31  32  33  34  35  36  37  38  39  3A  3B  3C  3D  3E  3F' 
Llne7  dc  h'20' 

dc  h'40  41  42  43  44  45  46  47  48  49  4A  4B  4C  4D  4E  4F' 

dc  h'50  51  52  53  54  55  56  57  58  59  5A  5B  5C  5D  5E  5F' 
Llne8  dc  h'201 

dc  h'60  61  62  63  64  65  66  67  68  69  6A  6B  6C  6D  6E  6F' 

dc  h'70  71  72  73  74  75  76  77  78  79  7A  7B  7C  7D  7E  7F' 
Line9  dc  h'20' 

dc  h'80  81  82  83  84  85  86  87  88  89  8A  8B  8C  8D  8E  8F' 

dc  h'90  91  92  93  94  95  96  97  98  99  9A  9B  9C  9D  9E  9F' 
LlnelO  dc  h'20' 

dc  h'AO  Al  A2  A3  A4  A5  A6  A7  A8  A9  AA  AB  AC  AD  AE  AF' 

dc  h'BO  Bl  B2  B3  B4  B5  B6  B7  B8  B9  BA  BB  BC  BD  BE  BF ' 
Linell  dc  h'201 

dc  h'CO  CI  C2  C3  C4  C5  C6  C7  C8  C9  CA  CB  CC  CD  CE  CF' 

dc  h'DO  Dl  D2  D3  D4  D5  D6  D7  D8  D9  DA  DB  DC  DD  DE  DF' 
Llnel2  dc  h'20' 

dc  h'EO  El  E2  E3  E4  E5  E6  E7  E8  E9  EA  EB  EC  ED  EE  EF' 
dc  h'FO  Fl  F2  F3  F4  F5  F6  F7  F8  F9  FA  FB  FC  FD  FE  FF' 

END 

*  DoChooseFont 

DoChooseFont  START 

using  GlobalDATA 
using  FontDATA 

PushLong  #0 
_GetPort 

PushLong  ITempPort 
_OpenPort 

PushLong  #0  .  „„,    , 

d„  ut    „  ,  '  sPace  for  result 

PushLong  DeslredFont 

PushWord  #0 

_ChooseFont 

Ida  l,s 
ora  3,s 
bne  ItChanged 

la  '■  ChooseFont  returned  a  0000,  so  the 

;  font  hasn't  changed 

PushLong  *TempPort 
_ClosePort 

_SetPort 

sec  .  , . 

_*  <  bad  return 

rts 


ItChanged  anop 
pla 


sta  DeslredFont 

pla 

sta  DesiredFont+2 

pushword  #0  .  „ 

PushWord  DeslredFont  '  """   ^   r6SUlt 
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PushLong  #R_Fname 

_GetFamInfo 

pla 

Ida  DesiredFont+3 

and  *$00FF 

pha 

Ida  #AR_FName 

pha 

Ida  R_FName 

and  #$00FF 

inc  a 

adc  #R_FName 

pha 

PushWord  #4 

PushWord  #0 

_Int2Deo 

Ida  R_FName 
lnc  a 
inc  a 
inc  a 
inc  a 
st a  R_FName 

PushLong  #TempPort 
_ClosePort 

_SetPort 

clc 
rts 


; ignore  result 

;  get  font  size  in  a  reg 

;  high  word  of  pointer  to  name 


;  low  word  of  pointer 
;  output  length 
;  not  signed 


bump  the  length 


;good  return 

;    size  of  graph  port 


TempPort  ds  $AA 
END 

* 

*  DispFontWindow 

************************.**,«*,,*****,,„ ************************** 
DispFontWindow  START 

using  FontDATA 

using  GlobalData 

********** 


*  get  my  own  zero  page 


phb 

phk 
plb 


phd 

Ida  MyZP 

ted 


get  the  correct  window  port  (got  here  from  within  taskmaster) 


********** 
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pushlong  #0 

_GetPort 

plx 

ply 

PUSHLONG  #0 

phy 

phx 

_GetWRefCon 

pla 

sta 

Temphandle 

plx 

stx 

TempHandle+2 

jsr 

Deref 

sta 

0 

stx 

2 

ldy 

♦oFontID+2 

Ida 

[01, y 

tax 

dey 

dey 

Ida 

[0],y 

jsl 

ShowFont 

Ida  TempHandle 
ldx  TempHandle+2 
jsr  Unlock 

pld 
plb 

rtl 

END 


;get  result  for  pushing  in  a  sec. 

; space  for  result 

,■  saved  the  port  here 


de  reference 


get  the  font  ID 


*********** 


ShowFont 


******************* 


i****************, 


*************** 


*  TnTTroutlne"?  t0  ^fr1^  ^^  thS  COnt6ntS  °f  the  Wl»<*ow. 
This  routine  Is  called  with  the  font  to  Insi-aii  <n  ,-►.- 
in  the  A  s  X  registers. 


the  font  to  install  In  the 


***************************** 

ShowFont  START 

using  GlobalData 
using  FontData 

phx 
pha 

phx 
pha 

PushWord  #0 
_InstallFont 

PushLong  #CurFontInfo 
_GetFontInfo 

stz  LineCounter 

clc 

Ida  CFAscent 


'****************** 


**************** 


;  save  copy  on  stack 
;  install  the  font 

;  Get  its  size  info 

;  zero  the  line  counter 

;  calculate  the  line  separation 


364 


Appendix  E:  HodgePodge  Source  Code:   Assembly  Language 


adc  CFDescent 
adc  CFLeading 
sta  CurHeight 

PushWord  #0 
PushWord  #0 
_MoveTo 

plx 

pushword  #0 

phx 

PushLong  #LineO 

_GetFamInfo 

pla 

pla 

xba 

and  #$00FF 

pha 

Ida  (TLineO 

pha 

Ida  LIneO 

and  #$00FF 

inc  a 

adc  #LineO 

pha 

PushWord  #4 

PushWord  #0 

_Int2Dec 

Ida  LineO 
inc  a 
inc  a 
inc  a 
inc  a 
sta  LineO 

PushWord  #0 
_GetFontFlags 

ldy  #oFlag 

Ida  [0],y 

lsr  a 

and  #$0001 

pha 

_SetFontFlags 


LineLoop  anop 


PushLong  #CurPos 
JSetPen 

PushWord  #5 

Ida  CurPos 

clc 

adc  CurHeight 

pha 

_MoveTo 

Ida  LineCounter 

asl  a 

tax 

phk 
phk 

ida  l,s 
and  #$00FF 
sta  l,s 


start  the  pen  position  at  0,0 


get  fontid  off  stack 

space  for  result 
family  number  was  in  x 


ignore  result 

high  word  of  font  id 
size  in  high  byte 


high  word  of  pointer  to  name 


low  word  of  pointer 
output  length 
not  signed 


bump  the  length 


save  prev  set  mono/pro  flag 


;  keep  the  result  on  the  stack  while 

;  we  set  it  to  what  we  want  (as 

;  defined  by  its  window  type  set  up 

;  when  we  opened  this  window) 


get  the  current  position 
;  reset  x  position 

and  y  position 
draw  current  line 
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Ida  LineTable,x 

pha 

_DrawString 

inc  LineCounter  .  bmnp  current  Une 

Ida  LineCounter 
cmp  #NuraLines 
bcc  LlneLoop 

_SetFontFlags  .  restore  from  saved  posltion 

rtl 

END 

*  doSetMono 

doSetMono      START 

using  FontData 
using  MenuData 

Ida  MonoFlag 
eor  #$02 
sta  MonoFlag 

beq  ChangeToMono         ; Change  message  to  show  effect  in 

PushLong  #PropStr        ;NEXT  selection  of  this  menu  item 

bra  PushID 
ChangeToMono   PushLong  #MonoStr 
PushID         PushWord  #MonoID 

_SetMItem 

rts 
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PRINT.ASM  (printing) 


*********************** ******* 


******************************** 


Hodgepodge:   An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


*    ASM65816  Code  file  "PRINT.ASM"  —  Print  dialogs;  Print  Manager  calls    * 


************ 


*************** 


****** 


********************************************* 


DoChooserltem 


*  This  is  the  routine  that  handles  the  Choose  Printer 

*  menu  item. 


DoChooserltem  START 

using  GlobalData 

PushWord  #0 

_PrChooser 

pla 

rts 

END 


******************************** 


**************************************************************** 

*  DoSetupItem 

*  This  is  the  routine  that  handles  the  page  setup  item. 

**************************************************************** 
DoSetupItem    START 

using  GlobalData 

Ida  PrintRecord 
ora  PrintRecord+2 
bne  AlreadyThere 

jsr  SetupDefault 

AlreadyThere   anop 
pha 

PushLong  PrintRecord 
_PrValldate 
pla 

Pushword  #0 
Pushlong  PrintRecord 


PRINT.ASM  (printing)  367 


_prStlDialog 
pla 

rts 

END 


****************** 

********* 


**************.*****»»*»***,*******„,„ 


*  SetupDefault 

* 

'   L^PrrntRe^rr"63  thS  dSfaUlt   ™«<=°^      **.  ^ndle 

SetupDefault   START 

using  GlobalDATA 

PushLong  #0 

PushLong  #140 

Pushword  My ID 

PushWord  #$8010 

PushLong  #0 

_newHandle 

pla 

sta  PrlntRecord 

pla 

sta  PrintRecord+2 

AlreadyThere   anop 

PushLong  PrlntRecord 
_prdefault 


END 


*********** 

******************** 


.....t,,,*,,,,,,,,,,,,,,,,,,,^^^ 


*  DoPrintltem 
* 

*  me  menu^  r°Utlne  "^   handl6S  the  print   item  in  the 


using  GlobalData 

pha 
pha 
GetPort 


get  the  current  port 


pha 

pha 

_FrontWlndow 

pla 


;  first  see  if  there  is  a  window 

;  to  print. 

;  and  save  pointer  to  it  now 

sta  WindowToPrint       '  ^^   any  dlal°9S  are  displayed  I 

pla 

sta  WindowToPrint+2 


ora  WindowToPrint 
bne  SomethingToPrint 
brl  Skiplt 

SomethingToPrint  anop 

Ida  PrlntRecord 
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AlreadySet 


continue 


Skiplt 


ora  PrintRecord+2 
bne  AlreadySet 

jsr  SetupDefault 

anop 

pha 

PushLong  PrintRecord 

_PrValidate 

pla 

PushWord  #0 
PushLong  PrintRecord 
_PrJobDialog 
pla 

bne  continue 
brl  skipit 

anop 

_WaitCursor 

PushLong  #0 

PushLong  PrintRecord 

PushLong  #0 

_PrOpenDoc 

pla 

sta  PrintPort 

pla 

sta  PrintPort+2 

PushLong  PrintPort 
PushLong  #0 
_PrOpenPage 

jsr  DrawTopWindow 

PushLong  PrintPort 
_PrClosePage 

PushLong  PrintPort 
_PrCloseDoc 

PushLong  PrintRecord 
PushLong  #0 
PushLong  #0 
_PrPicFile 

_InitCursor 

anop 

_SetPort 

rts 
END 


space  for  result 

ignore  result  since  all  is  well  now 


restore  original  port 
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******#********A**#j,*********ln*t***1m(#1m*+1mJ[tiMmii4lHr1mlt 


*  DrawTopWindow 


DrawTopWindow  START 

using  GlobalDATA 
pha 
pha 

PushLong  WindowToPrint 
GetWRefCon 


space  for  result  of  GetWRefCon  call 


pla 

st a  TheRefCon 

plx 

stx  TheRefCon+2 

jsr  Deref 

sta  0 

stx  2 

ldy  #oFlag 

Ida  [0],y 

beq  UsePaint 


ldy  #oFontID+2 

Ida  [0],y 

tax 

dey 

dey 

Ida  [0],y 

jsl  ShowFont 

bra  AllDone 


UsePaint 


anop 

ldy  #oHandle+2 

Ida  [0],y 

tax 

dey 
dey 
Ida  [0],y 

jsl  Paintlt 


;  get  handle  to  pic  data 


AllDone 


Ida  TheRefCon 
ldx  TheRefCon+2 
jsr  Unlock 


rts 


theRefCon 


ds   4 


WindowToPrint  ENTRY 
ds  4 


END 
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IO.ASM  (pictures  and  files) 


****************************************** 


********** 


HodgePodge:   An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


ASM65816  Code  file  "IO.ASM"  ~  Picture  Load  and  Save  stuff  calling  ProDOS  * 


********** 


**************** 


k ********  ********************** 


************ 


********************************************* 


*  LoadOne 

*  Loads  the  picture  whose  path  name  is  passed  in 

W 

*  NamePtr 

*  to  address  passed  in 

* 

*  PicDestIN 


********** 

*********************** 

LoadOne 

START 

using  IOData 

_OPEN  OpenParams 

bcc  contl 

jmp  Errorl 

contl 

a  nop 

Ida  OpenID 

sta  ReadID 

sta  CloselD 

_READ  ReadParams 

bcc  cont2 

jmp  Errorl 

cont2 

anop 

_Close  CloseParams 

clc 

rts 

end 
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A*****************************, 


•  l**«HinHHl,i««HHim)t« 


*  SaveOne 

*  Saves  the  picture  whose  path  name  is  passed  in 

*  NamePtr 

*  from  address  passed  in 

*  PicDestOUT 


******************************* 
SaveOne        START 

using  IOData 

Ida  NamePtr 

sta  NameC 

st a  NameD 

Ida  NamePtr+2 

sta  NameC+2 

sta  NameD+2 


**************************** 


_Destroy  DestParams 

Ida  #$cl 
sta  CType 
Ida  #0 
sta  CAux 


;  SuperHires  picture  type 
;  standard  type  =  0 


ContO 


contl 


_Create  CreateParms 
bcc  contO 
jmp  Errorl 

_OPEN  OpenParams 
bcc  contl 

jmp  Errorl 

a  nop 

Ida  OpenID 
sta  WritelD 
sta  CloselD 


cont2 


_WRITE  WriteParams 
bcc  cont2 
jmp  Errorl 

a  nop 

_Close  CloseParams 

clc 
rts 
end 


******************* 


*************** 


********** 


*  Errorl  —  handle  disk  error  during  read  or  write 


******************* 
Errorl 


********************************* 
START 
using  IOData 
pha 

_Close  CloseParams 
pla 

jsr    CheckDiskError 
rts 


END 
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GLOBALS.ASM  (global  data) 


************************************************ 


******************** 


Hodgepodge:  An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


*  ASM65816  Code  file  "GLOBALS.ASM"  —  Global  variables  and  misc.  routines   * 


********** 


************************* 


******************************** 


**************************************************************** 


*  GlobalDATA 


******************* 


GlobalData 


******************************************* 


Prompt 
Prompt  2 
Wxoffset 
Wyoffset 

null Re ct 

reply 
rjjood 
r__type 
r_auxtyp 

r_fname 
r_fullpn 


dc   11 '19' ,c' Load  which  Picture:' 

dc  il'19',c'Save  which  Picture:' 

dc  i'20'     ;  offset  for  upperleft  window  corner 

dc  i'12'     ;  offset  for  upperleft  window  corner 


dc  l'O, 0,0,0' 

a  nop 
dc  12" 0' 
dc  i2'0' 
dc  12'0' 
ds  16 
ds  128 


;SF  GET/PUT  FILE  record 


QuitParams 


dc  i4'0' 
dc  i'$4000' 


am  restartable  in  memory 


;  ToolTable 


dc 
dc  i' 
dc 
dc 
dc 
dc 
dc 
dc 

dc  i 
dc  i 
dc  i 
dc  i 


I'll' 

4, $0101' 
5, $0100' 
6, $0100' 
14, $0103' 
15, $0103' 
16, $0103' 
20, $0100' 
21, $0100' 
23, $0100' 
27, $0100' 
28, $0000' 


;  ThisMode 


dc  i'$0080' 


quickdraw 

desk  manager 

event  manager 

window  manager  from  disk! 

menu  manager  from  Disk! 

control  manager  form  disk! 

line  edit 

dialog  manager  from  disk! 

standard  files  from  disk! 

Font  manager 

List  manager 

;init  mode:  640 


SrcLocInfo 
PicPtr 


dc  i'SSO" 
ds  4 


;PPtoPort  640  parms 
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SrcRect 

Event Record 

EventWhat 

EventMessage 

EventWhen 

EventWhere 


do  i'160' 

dc  i'0,0,200,640' 

dc  i'0,0,200,640' 

a  nop 
ds  2 
ds  4 
ds  4 
ds  4 


EventModifiers  ds  2 


TaskDATA 
TaskMask 

QuitFlag 

DialogPtr 

Windex 

LastWind 

MyZP 

;  ZpHandle 

;  MylD 


ds  4 

dc  i4"$0FFF' 

ds  2 
ds  4 
ds  2 
gequ  15 
ds  2 

ds  4 

ds  2 


; Index  to  next  avail. window  ID 
/Maximum  number  of  windows  open 


Vindex 

Vtable 

WindowList 

WhichWindow 

TempHandle 

Temp2Handle 

PicHandle 

SavePort 

SaveType 

ActlvateFlag 

NeedToUpdate 

ThisWType 

LastWtype 

PrintAvail 

PrintRecord 
PrintPort 

VolNotFound 


ds  2 
ds  16*4 
ds  16*4 
ds  4 
ds  4 
ds  4 

•'- 

4 

. 

2 

2 

i'0> 


■:y 
::. 
: 

-: 
::: 
:•■• 
;• 

: 


ds  4 
ds  4 

gequ  $45 


; index  used  to  list  of  what  WAS  visible 
;list  of  what  WAS  vis.  when  Hiding  all 
;all  windows  handle  go  into  this  list 
;will  contain  window  pointer,  cur.  window 
;some  temp  handles 

;  handle  to  picture  data 

;Save  current  port  env  for  ShowPlWait 

;flag  for  check  front  window. 
;used  to  prevent  multi  menu  redraws 


;Make  sure  this  starts  as  0 

;  handle  to  print  record 

;  pointer  to  printing  GrafPort. 

;  prodos  error 


MyWindowInfo 

This  is  the  data  structure  used  for  the  windows  we 
allocate. 


MaxNameSize    equ  29 


oHandle 

oBlank 

oLength 

oName 

oMMStuff 

oFlag 

oExtra 

oFontID 


MyWinfoSize 


equ  0 

equ  oHandle+4 

equ  oBlank+1 

equ  oLength+1 

equ  oName+MaxNameSi ze 

equ  oMMStuff+6 

equ  oFlag+1 

equ  oHandle 


equ  oExtra+4 

v 


largest  name  we  allow 


if  the  type  is  for  font, 
the  first  field  is  a  FontID 
rather  than  the  handle  to  picture 
data. 
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jurce  Code: 


Assembly  Language 


ft*************** 


It************************ 


****************** 
IOData      DATA 


******** 


******************** 


CreateParms  anop 


NameC 


dc 


14'0' 


dc 

i2'$00C3' 

CType         dc 

i2'S0006' 

CAux           dc 

14 '$00000000' 

dc 

12'$0001' 

dc 

12 '$0000' 

dc 

12 '$0000' 

DestParams 

anop 

NameD 

dc          14 '0' 

OpenParams 

anop 

OpenID 

ds   2 

NamePtr 

ds   4 

ds  4 

ReadParams 

anop 

ReadID 

ds  2 

PicDestIN 

ds   4 

dc   14 '$8000' 

ds   4 

PReadParams 

anop 

PReadID 

ds  2 

PReadLoc 

ds  4 

PReadSize 

ds   4 

ds   4 

MarkParams 

anop 

MarkID 

ds  2 

CurrentMark 

anop 

Mark 

ds   4 

WriteParams 

anop 

WritelD 

ds  2 

PicDestOUT 

ds   4 

dc   14 '$8000' 

ds   4 

CloseParams 

anop 

CloselD 

ds   2 

;  DRNWR 

;  BIN 

;  Aux . 

;  type 

;  create  date 

;  create  time 


this  many  bytes 
how  many  xfered 

for  reading  a  packed  file 


this  many  bytes 
how  many  xfered 


this  many  bytes 
how  many  xfered 


END 
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*****************************************************irmi[ititiriti[il 

*  Ignore 

*  Does  not  do  a  whole  lot. 

Ignore         START 
rts 
END 

******************************  I-********************************* 
* 

*  Deref 

*  Deref s  and  locks  the  handle  passed  in  a,x.  Result  passed  back 

*  in  a,x.  Trashes  0  on  zp. 

* 

******************************************************1l1l******** 
Deref         START 

sta  0 

stx  2 

ldy  #4 

Ida  [0],y 

ora  #$8000 

sta  [0],y 

dey 

dey 

Ida  [0],y 

tax 

Ida  [0] 

rts 

END 

*************************  ****************************  I,********** 

* 

*  Unlock 


*  Unlocks  the  handle  passed  in  x  and  a.   0  is  trashed  on 


zp. 


*************  *************************************  ************** 
Unlock         START 

sta  0 
stx  2 

ldy  #4 
Ida    [0J,y 
and  #S7FFF 
sta    [0],y 
rts 


.END 


END 
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Appendix  F 


HodgePodge   Source 
Code:     C 


HP.CC  378 
MENU.CC  382 
EVENT.CC   385 
WINDOW.CC   390 
DIALOG.CC  400 
FONT.CC  405 
PRINT.CC  409 
HP.H  411 
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HP.CC  (main  program) 


*  * 

*  Hodgepodge:   An  example  Apple  IIGS  Desktop  application  * 

Written  by  the  Apple  IIGS  Development  Team  * 

*  C  Versionn  4.0  * 

*  * 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc.  * 

*  All  Rights  Reserved  « 


This  program  and  its  derivatives  are  licensed  only  for 
use  on  Apple  computers. 

Works  based  on  this  program  must  contain  and 
conspicuously  display  this  notice. 

This  software  is  provided  for  your  evaluation  and  to 
assist  you  in  developing  software  for  the  Apple  IIGS 
computer. 

This  is  not  a  distribution  license.  Distribution  of 
this  and  other  Apple  software  requires  a  separate 
license.  Contact  the  Software  Licensing  Department  of 
Apple  Computer,  Inc.  for  details. 

DISCLAIMER  OF  WARRANTY 

THE  SOFTWARE  IS  PROVIDED  "AS  IS"  WITHOUT 
WARRANTY  OF  ANY  KIND,  EITHER  EXPRESS  OR  IMPLIED, 
WITH  RESPECT  TO  ITS  MERCHANTABILITY  OR  ITS  FITNESS 
FOR  ANY  PARTICULAR  PURPOSE.   THE  ENTIRE  RISK  AS  TO 
THE  QUALITY  AND  PERFORMANCE  OF  THE  SOFTWARE  IS  WITH 
YOU.   SHOULD  THE  SOFTWARE  PROVE  DEFECTIVE,  YOU  (AND 
NOT  APPLE  OR  AN  APPLE  AUTHORIZED  REPRESENTATIVE) 
ASSUME  THE  ENTIRE  COST  OF  ALL  NECESSARY  SERVICING, 
REPAIR  OR  CORRECTION. 

Apple  does  not  warrant  that  the  functions 
contained  in  the  Software  will  meet  your  requirements 
or  that  the  operation  of  the  Software  will  be 
uninterrupted  or  error  free  or  that  defects  in  the 
Software  will  be  corrected. 

SOME  STATES  DO  NOT  ALLOW  THE  EXCLUSION 
OF  IMPLIED  WARRANTIES,  SO  THE  ABOVE  EXCLUSION  MAY 
NOT  APPLY  TO  YOU.   THIS  WARRANTY  GIVES  YOU  SPECIFIC 
LEGAL  RIGHTS  AND  YOU  MAY  ALSO  HAVE  OTHER  RIGHTS 
WHICH  VARY  FROM  STATE  TO  STATE. 


Source   file  HP.CC  —   Startup  and   Shutdown  routines 

♦include  <types.h> 
♦include  <prodos.h> 
♦include  <misctool.h> 
♦include  <quickdraw.h> 
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•include 
•include 
It  include 
♦include 
♦include 
•include 
•include 
•include 
•include 
•include 
(include 
•include 
•include 
•include 
•include 
•include 
•include 
•include 


<qdaux . h> 

<wlndow.h> 

<memory .  h> 

<dialog.h> 

<menu.h> 

<control .h> 

<desk.h> 

<event . h> 

<lineedlt.h> 

<misctool.h> 

<locator.h> 

<stdflle.h> 

<print.h> 

<font.h> 

<intmath.h> 

<list.h> 

<scrap.h> 

"hp.h" 


extern  int     toolErr; 


boolean  ToolsFound  -  FALSE, 

AllOk  =  FALSE, 

PManagerFound     =  TRUE; 


/*  Do  we  have  tools   ?   */ 

/*   assume  the  PM  is  there   */ 


int  MylD; 

int  ThisMode  =  0x80; 

int  ToolTable  []  -  (14 

r 

/ 

4, 

0x100, 

/ 

5, 

0x100, 

/ 

6, 

0x100, 

/ 

14, 

0x100, 

/ 

15, 

0x100, 

/ 

16, 

0x100, 

/ 

18, 

0x100, 

/ 

19, 

0x000, 

/ 

20, 

0x100, 

/ 

21, 

0x100, 

/ 

22, 

0x100, 

/ 

23, 

0x100, 

/ 

27, 

0x100, 

/ 

28, 

0x0001; 

/ 

/*   lnit  mode  =   640   */ 

Number  of  items  */ 
QuickDraw  II  */ 
Desk  Manager  */ 
Event  Manager  */ 
Window  Manager  */ 
Menu  Manager  */ 
Control  Manager  */ 
QuickDraw  Auxiliary  */ 
Print  Manager  */ 
Line  Edit  */ 
Dialog  Manager  */ 
Scrap  Manager  */ 
Standard  File  */ 
Font  Manager  */ 
List  Manager  */ 


char  **y,*z; 


GrafPortPtr  OrigPort; 


/*  This  Is  the  routine  that  will  do  the  initialization  of  tools,  will  allocate 
memory  and  all  related  tasks 


boolean  StartUpTools  () 


static  char     SysToolsDirStr  []  =  "\p*/SYSTEM/TOOLS"; 
static  FileRec  ParamBlock  =  (  SysToolsDirStr  ,  NULL  ); 


TLStartUp    ()  ; 


/*   for   calling  tools   */ 


HP.CC  (main  program) 
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CheckToolError  (1); 


MylD  =  MMStartUpO; 
CheckToolError  (2); 

MTStartUpO; 
CheckToolError  (3)  ; 

y  =  NewHandle  (OxBOOL, 
MylD, 

attrBank  + 
attrPage  + 
attrFlxed  + 
attrLocked, 
OL)  ; 

CheckToolError  (4); 


/*  ID  for  all  transactions  */ 


/*  Misc.  Tools  */ 

/*  Make  sure  all  Is  OK 

/*  Eleven  pages         */ 
/*  put  It  to  my  name    */ 


/*  don't  care  */ 


z  =  *y; 

QDStartUp  ((lnt)  z,ThisMode,MAXSCAN,MyID)  ; 
CheckToolError  (5); 
OrigPort  =  GetPort  ()  ; 

EMStartUpf  (int)  z  +  0x300, 20, 0, 640, 0,200, MylD) ; 
CheckToolError  (6); 


/*  deref  handle 


/*  Event  Manager  */ 


MoveTo  (20,20); 

SetBackColor  (0)  ; 

SetForeColor  (15); 

Drawstring  ("\pOne  Moment  Please. 

ShowCursor  (); 

Try Again: 

GET_FILE_INFO  (SParamBlock) ; 
If  (_toolErr) 

If  (MountBootDlsk  ()  -=  1) 

goto  TryAgain; 
else 

return  (false) ; 

LoadTools  (ToolTable) ; 
CheckToolError  (7); 


/*  Exit  function  unsuccessfully  */ 
/*  Now  it's  ok  to  do  this  */ 


QDAuxStartUp  (); 
CheckToolError  (8); 

WaitCursor  ()  ; 

WindStartUp  (MylD) ; 
CheckToolError  (9); 

RefreshDesktop  (NULL) ; 

CtlStartUp  (MylD, (int)  z  +  0x400); 
CheckToolError  (10); 

LEStartUp  (MylD,  (int)  z  +  0x500); 
CheckToolError  (11) ; 

DialogStartUp  (MylD) ; 
CheckToolError  (12); 

MenuStartUp  (MylD,  (int)  z  +  0x600); 
CheckToolError  (13) ; 

DeskStartUpO  ; 
CheckToolError  (14)  ; 


/*  Show  wristwatch  cursor  */ 


/*  All  we  need  is  init'ed  now  */ 
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ShowPleaseWait  () ; 

SFStartUp (MylD,  (int)  z  +  0x700); 
CheckToolError  (15) ; 
SFAllCaps  (true) ; 


FMStartUp  (MylD,  (int)  z  +  0x800); 
CheckToolError  (16) ; 


/*  the  watch  cursor  is  up  */ 
/*  while  we  count  the  fonts  */ 


ListStartup  (); 
CheckToolError  (17) ; 


/*  >!<  Note,  not  ListStartup  with  upper  case  "U"! 


ScrapStartUp  ()  ; 
CheckToolError  (18) ; 

PMStartUp  (MylD,  (int)  z  +  0x900); 
CheckToolError  (19); 


HidePleaseWait  () ; 
InitCursor  () ; 


/*  Remove  dialog  box  */ 
/*  Show  arrow  cursor  */ 


return  (true)  ; 


/*  Exit  function  successfully  */ 


ShutDownTools  () 


DeskshutDown  (); 


if  (WindStatus  ()  !-  0) 
HideAllWindows  (); 


ListShutDown 

FMShutDown 

ScrapShutDown 

PMShutDown 

SFShutDown 

MenuShutDown 

DialogShutDown 

LEShutDown 

CtlShutDown 

WindShutDown 

QDAuxShutDown 

EMShutDown 

QDShutDown 

MTShutDown 


if    (MMStatus    ()    !=  0) 
( 

DisposeHandle    (y) ; 

MMShutDown  (MylD)  ; 

) 
TLShutDown    ()  ; 


/*  MAIN  program  routine  */ 

main    () 
( 

if    (StartUpTools    () ) 
1 

SetUpMenus    (); 
MainEvent      () ; 
) 
ShutDownTools    ()  ; 


/*  Try  to  initialize  tools 


/*   Shutdown  tools  even  if  didn't  run  */ 


HP.CC  (main  program) 
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MENU.CC  (menus) 


*      Hodgepodge:  An  example  Apple  IIGS  Desktop  application       * 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


*   Source  file  MENU.CC  -  Menu  bar  inserting/deleting  /  vectoring   * 

•include  <types.h> 
♦include  <menu.h> 
♦include  <desk.h> 
♦include  <window.h> 
♦include  <memory.h> 
♦include  <intmath.h> 
♦include  <misctool.h> 
♦include  <texttool.h> 
♦include  "hp.h" 

/*  Bunch  of  routines  defined  somewhere  else  */ 

extern  DoCloseItem()  ; 

extern  DoAboutltemO  ; 

extern  DoQuitltem  ()  ; 

extern  DoOpenltem  ()  ; 

extern  DoSaveltemO  ; 

extern  DoChooserltem  ()  ; 

extern  DoSetUpItemj) ; 

extern  DoPrintltemf)  ; 

extern  DoChangeRes () ; 

extern  DoCpenltemO  ; 

extern  DoSetMonoO; 

extern  DoShowVers  ()  ; 

extern  WmTaskRec  TheEvent; 
extern  GrafPortPtr  WhichWindow; 
extern  GrafPortPtr  WindowList [16] ; 
extern  int  Windex; 

char  IDStr[8]  =  "\\N300\r"; 
extern  char  str[]  ; 

/*  Here  we  have  all  defines  for  all  the  menus  */ 

char  *Menus[]  =  { 

/*  Fonts  menu  */ 

"»  Fonts  \\N6\r\ 

"-Display  Font  . . .\\*FfN264\r\ 

"Display  Font  as  Mono-spaced\\*MmN265\r. ",   /.  compiler  adds  '0'  at  the  end  V 

/*  Windows  menu  */ 

"»  Window  \\DN5\r\ 

==No  Windows  Allocated\\N299\r.", 
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/*  Edit  Menu  */ 

"»     Edit      \\DN3\r\ 

==Undo\\*ZzN250\r\ 

— \\N298D\r\ 

"Cut\\*XxN251\r\ 

"Copy\\*CcN252\r\ 

"Paste\\*WN253\r\ 

"Clear\\N254\r.", 

/*  File  Menu  */ 

"»     File     \\N2\r\ 

"Open   ...\\*OoN258\r\ 

"Close\\DN255\r\ 

==Save  As    . .  .\\DN259\r\ 

— \\N298D\r\ 

"Choose  Printer... \\N260\r\ 

"Page  Setup   . . .\\DN261\r\ 

"Print    .  ..\\D*PpN262\r\ 

— \\N298D\r\ 

"Quit\\*QqN257\r.", 

/*  Apple  Menu   */ 

"»e\\XNl\r\ 

"About  Hodgepodge.. .\\N256\r\ 

"-WN298D."}; 


AddToMenuO 

I 

DataRecPtr  dereftemp; 

DataRecHandle  TempHandle; 

int  index, i; 


WhichWindow  -  FrontWindowO  ; 

TempHandle  =    (DataRecHandle)    GetWRefCon (WhichWindow) ; 

dereftemp  -   "TempHandle; 
HLock (TempHandle) ; 

Int2Dec(Windex,IDStr  +  3,2,0); 
IDStr[3)     |-  0x30; 
IDStr[4]     |-  0x30; 

index  =    (dereftemp  ->   Str[0])    +    1; 
for   (i=0;i  <=6;i++) 

dereftemp  ->   Str[i   +   index]    -  IDStr[i]; 


InsertMItem(s  (dereftemp  ->   Blank)  ,0xffff, WindowsMenuID)  ; 

if   (!(Windex))  /*  this  is  the  first  window  */ 

( 
DeleteMItem(299);  /*   Token  item       */ 

SetMenuFlag(0xff7f, WindowsMenuID);  /*  highlight   the  menu        */ 

DrawMenuBar  ()  ; 
) 
CalcMenuSize (0L, WindowsMenuID) ; 
WindowList  [Windex]    =  WhichWindow; 
Windex++; 
HUnlock  (TempHandle)  ; 


DoWItemO 
I 

WhichWindow=WindowList [ (TheEvent.wmTaskDatasOxf f f f )    -  300    ]j 

DoWindow(); 

HiliteMenu (FALSE,    TheEvent.wmTaskData/Oxf f ff ) ; 
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DoMenu ( ) 
( 


switch  (TheEvent.wmTaskData  &   Oxffff) 


case  UndoID 
case  Cut ID 
case  Copy ID 
case  PastelD 
case  ClearlD 
case  CloseWID 

case  About ID 

case  QuitID 

case  OpenWID 

case  SavelD 

case  ChooselD 

case  SetUpID 

case  PrintID 

case  ShowFontID 

case  MonoID 

case  299 

default 


:  break; 
:  break; 
:  break; 
:  break; 
:  break ; 
:  DoCloseltemO  ; 

break; 
:  DoAboutltemO  ; 

break; 
:  DoQuitItem(); 

break; 
:  DoOpenltemO; 

break; 
:  DoSaveltemf); 

break; 
:  DoChooserltem  () ; 

break; 
:  DoSetUpItemO; 

break; 
:  DoPrintltemO; 

break; 
:  DoOpenltemO; 

break; 
:  DoSetMonof); 

break; 
:  break; 
:  DoWltemO; 


/*  we  do  nothing  with  */ 


/*  these  ! 


HiliteMenu (FALSE,  TheEvent .wmTaskData/Oxffff ) ■ 


SetUpMenus  () 


( 


int  MenuLooper; 
SetMTitleStart  (10); 


/*  Set  starting  pos  of  menus  */ 


for  (MenuLooper  -  0;   MenuLooper  <  NUM  MENUS;   MenuLoocer++) 
InsertMenu  (NewMenu  (Menus  [MenuLooper] )  ,0) ;  MenuLooper++» 


FixAppleMenu  (AppleMenuID) ; 
FixMenuBar    ()  ; 
DrawMenuBar   ()  ; 


/*  Add  NDA's,  if  any  */ 

/*  Set  sizes  of  menus  */ 

/*  Draw  the  menu  bar  on  the  screen  */ 
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EVENT.CC  (main  event  loop) 


i  . 


/*************** ********************************************** 

Hodgepodge:  An  example  Apple  IIGS  Desktop  application 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


*  Source  file  EVENT.CC  —  Main  event  loop  and  window  activation 

* 
******************************************************************** 

•  include  <types.h> 

•  include  <memory.h> 
♦include  <window.h> 
♦include  <prodos.h> 

♦  include  <misctool.h> 

♦  include  <texttool.h> 
♦include  <menu.h> 
♦include  "hp.h" 

extern  int  _toolErr; 
extern  PManagerFound; 

int  QuitFlag  -  0; 
GrafPortPtr  LastWindow  -  NIL, 
ThisWindow  -  NIL; 

int  ActivateFlag; 

struct  HandleRec    ( 

char  *ptrpart; 

int  flags; 
); 
/*  for  Open 

typedef  struct  OpenRec  ( 
Word     openRefNum; 
Ptr      openPathname; 
Handle   iOBuffer; 

)  OpenRec,  *OpenRecPtr,  **OpenRecHndl; 
V 

OpenRec  MyOpenParams  =  (0,0,0L); 

/*  for  Read,  Write,  Close,  Flush 

typedef  struct  FilelORec  ( 
Word     fileRefNum; 
Ptr      dataBuffer; 
Longint  requestCount; 
Longint  transferCount; 
)  FilelORec,  *FileIORecPtr,  **FileIORecHndl;   */ 
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FilelORec  ReadParams  =  ( 


0, 

0L, 

0x8000L, 

OL); 


FilelORec  WriteParams  =  ( 

0, 

OL, 

0X8000L, 

OL); 

FilelORec  CloseParams; 

/*  for  Create,  SetFilelnfo,  GetFilelnfo 

typedef  struct  FileRec  { 
Ptr      pathname; 
Word     fAccess; 
Word     fileType; 
Longint   auxType; 
Word     storageType; 
Word     createDate; 
Word     createTime; 
Word     modDate; 
Word     modTime; 
Longint  blocksUsed; 
)  FileRec,  *FileRecPtr,  **FlleRecHndl; 


/*  fileRefNum 
/*  dataBuffer 

/*  requestCount 
/*  transferCount 


/*  fileRefNum 
/*  dataBuffer 

/*  requestCount 
/*  transferCount 


/*  most  remains  unused  */ 


FileRec  CreateParams 


( 


OL, 

0x00c3, 

0x0006, 

0L, 

1, 

0,0, 

0,0, 

0L); 

/*  for  Destroy,  ChangePath,  ClearBackupBit,  GetPathname,  GetBootVol 

typedef  struct  PathNameRec  ( 
Ptr      pathname; 
Ptr      newPathname; 
)  PathNameRec,  *PathNameRecPtr,  **PathNameRecHndl; 

PathNameRec  DestParams  =  (0L,0L); 

WmTaskRec  TheEvent; 

MainEvent () 

( 

int  My Event; 


TheEvent. wmTaskMask  =  OxOOOOOfff; 

do 


/*  initialize  mask  */ 


( 


do 


ActivateFlag  -  0; 

CheckFrontW  (); 

MyEvent  =  TaskMaster (OxFFFF,  STheEvent) ; 
} 
while (! MyEvent) ; 
switch  (MyEvent) 
( 


386  Appendix  F:  HodgePodge  Source  Code:    C 


case     aotivateEvt   :   De-Activate    (); 
break ; 

case  17:  /*  in  menu  */ 

DoMenu ( ) ; 
break; 

case  22:  /*  in  goaway  */ 

DoCloseltemO  ; 
break; 

case  25:  /*  in  special  menu  item  */ 

DoMenu ( ) ; 
break ; 
) 
I 
while  (!  (QuitFlag))  ; 
I 

DoQuitItem() 
I 

QuitFlag  =  0x8000;  /*  simple  uh?  */ 

/*  Check  if  the  front  window  has  changed  and  react  accordingly  */ 

CheckFrontWO 
I 

DataRecHandle  TempDataHand; 
DataRecPtr  TempDataPtr; 

ThisWindow  -  FrontWindowO  ; 
if  (!  (ThisWindow  --  Lastwindow) ) 
{ 
if  (Lastwindow  =  ThisWindow)  /*  at  least  one  window  */ 

( 

if  ( ! (GetSysWFlag (ThisWindow) ) ) 
{ 

SetUpForAppW()  ; 
if  (ActivateFlag) 

TempDataHand  -  (DataRecHandle) GetWRefCon (TheEvent .wmTaskData) ; 
else 

TempDataHand  =  (DataRecHandle) GetWRefCon (ThisWindow) ; 
TempDataPtr  -  'TempDataHand; 
HLock  (TempDataHand) ; 
if  (TempDataPtr  ->  Flag) 
DisableMItem  (SavelD) ; 
else 

EnableMItem  (SavelD) ; 
HUnlock (TempDataHand) ; 
I 
else 

SetUpForDaW ( ) ; 
1 
else 

DlsableAlK); 
) 


DoActivateO 
I 

if  (TheEvent .wmModifiers  s  1) 
( 
ActivateFlag  =  1; 
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CheckFrontW  (); 
) 


/*  Disable  items  not  applicable  */ 

DisableAll  () 
1 

SetMenuFlag   (0x0080, EditMenuID) ;  /*  disable  */ 

DrawMenuBar   (); 
Disableltems  (); 
) 

SetUpForAppW  () 
( 

SetMenuFlag  (0x0080, EditMenuID) ; 

DrawMenuBar  ()  ; 

Enableltems  (); 
} 

SetUpForDaWO 
I 

Disableltems  () ; 

EnableMItem  (CloseWID)  ; 

SetMenuFlag (Oxf f 7f , EditMenuID) ; 
DrawMenuBar  ()  ; 
) 

Enableltems  () 
{ 

EnableMItem (SavelD) ; 
EnableMItem (CloseWID) ; 
if  (PManagerFound) 
I 

EnableMItem (PrintID);  /*  don't  enable  if  printing  */ 

EnableMItem (SetUpID);  /*  is  out  of  the  question!   */ 

) 
} 

Disableltems () 
1 

DisableMItem(SavelD) ; 

DisableMItem (CloseWID) ; 

DisableMItem (PrintID) ;  /*  who   cares!?    */ 

DisableMItem (SetUpID) ; 
) 

I*   Now  some  I/O  stuff,  this  file  is  just  Ok  for  it  */ 

boolean  LoadOneO 
1 

OPEN(SMyOpenParams) ; 
if  (_toolErr) 
{ 

CheckDiskError  (1) ; 

return (FALSE) ;  /*  couldn't  open  */ 

) 
else 
! 

ReadParams.fileRefNum  -  MyOpenPararas.openRefNum; 
CloseParams.fileRefNum  -  MyOpenParams.openRefNum; 
READ (SReadParams) ; 
if  (_toolErr) 
I 

CLOSE (SCloseParams) ; 
CheckDiskError (2)  ; 
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return (FALSE) ; 
1 
else 
( 

CLOSE (SCloseParams) ; 

return (TRUE) ; 
I 


SaveOneO 

CreateParams. pathname  =  MyOpenParams.openPathname; 
DestParams. pathname  =  MyOpenParams.openPathname; 
CloseParams.fileRefNum  =  MyOpenParams.openRefNum; 
CreateParams. fileType  -  Oxcl; 
CreateParams. auxType  -  0; 

DESTROY  (SDestParams) ; 

CREATE (sCreateParams) ; 
if   (_toolErr) 
( 
CLOSE (sCloseParams) ; 
CheckDiskError(3); 
) 
else 
I 
OPEN  (sMyOpenParams) ; 
if   (_toolErr) 
( 

CLOSE (SCloseParams) ; 
CheckDiskError (4) ; 
1 
else 
( 
WriteParams.fileRefNum  =  MyOpenParams.openRefNum; 
WRITE (sWriteParams) ; 
if    (_toolErr) 
( 

CLOSE (SCloseParams)  ; 
CheckDiskError (5) ; 
) 
else 

CLOSE (SCloseParams) ; 
) 
) 
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WINDOW.CC  (windows) 


/A***********************************  ****************************  *  *  *  *  * 

*  * 

*  Hodgepodge:   An  example  Apple  IIGS  Desktop  application        * 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


*  Source  file  WINDOW.CC  —  Window  opening  /  closing 

•  a*********************************************************.****.* 

♦include  <types.h> 
♦include  <quickdraw.h> 
♦include  <window.h> 
♦include  <stdfile.h> 
♦include  <prodos.h> 
♦include  <memory.h> 
♦include  <qdaux.h> 
♦include  <font.h> 
♦include  <menu.h> 
♦include  <desk.h> 
♦include  <misctool.h> 
♦include  <texttool.h> 
♦include  <intmath.h> 
♦include  "hp.h" 

extern  GrafPortPtr  OrigPort; 

extern  char  str[]; 

/*  stuff  to  define  the  window  data  structure,  defined  in  HP.H 

typedef  struct  DataRec  ( 

handle  PicHand; 

char  Blank; 

char  Str[30],- 

char  MMStuff [6]; 

Byte  Flag; 

char  Extra; 

)  DataRec,  *DataRecPtr,  **DataRecHandle; 
*/ 

DataRecHandle  MyDataHandle; 
DataRecPtr  RefPtr; 

/*  This  structure  is  defined  in  window. h 
typedef  struct  WmTaskRec  { 


Word 

wmWhat ; 

DblWord 

wmMessage; 

DblWord 

wmWhen; 

Point 

wmWhere; 

Word 

wmModifiers; 

DblWord 

wmTaskData; 

DblWord 

wmTaskMask; 

)  WmTaskRec,  *WmTaskRecPtr,  **WmTaskRecHndl; 

extern  WmTaskRec  TheEvent; 
extern  char  *LineTable [ ] ; 
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extern  int  _toolErr; 
extern  int  MylD; 
extern  int   ThisMode; 


extern  Get Put Tempi ate   SFP640Temp;  /*  templates   for   StdFile   */ 

char  origitem[]    -  "=-No  Windows  Allocated\\N299\r";    /*   first   item  in  windows   */ 


extern  int  MonoFlag; 
extern  FontID  DesiredFont; 

extern  int  Paint  ()  ; 

extern  int  DispFontWindowO  ; 

pascal   int  OpenFilter  ()  ; 


/*  see  Font.c   */ 
/*   */ 

/*  window  content  proc  */ 
/*  Window  def  Proc  for  fonts  */ 


/*  typedef  struct  ParamList  ( 

Integer 

paramLength; 

Word 

wFrameBits; 

Ptr 

wTitle; 

long 

wRefCon; 

Rect 

wZoom; 

Ptr 

wColor; 

Integer 

wYOrigin; 

Integer 

wXOrigin; 

Integer 

wDataH; 

Integer 

wDataW; 

Integer 

wMaxH; 

Integer 

wMaxW; 

Integer 

wScrollVer; 

Integer 

wScrollHor; 

Integer 

wPageVer; 

Integer 

wPageHor; 

DblWord 

wlnfoRefCon; 

Integer 

wlnfoHeight; 

Ptr 

wFrameDefProc; 

Ptr 

wlnfoDefProc; 

Ptr 

wContDefProc; 

Rect 

wPosition; 

WPortPtr 

wPlane; 

WindRecPtr 

wStorage; 

)  ParamList 

,  *ParamListPtr,  **ParamListHndl 

ParamList  MyWindow  -  ( 

sizeof (MyWindow) , 

/ 

OxddaO, 

/ 

OL, 

/ 

OL, 

/ 

0,0,0,0, 

/ 

OL, 

/ 

0, 

/ 

0, 

/ 

200, 

/ 

640, 

/ 

200, 

/ 

640, 

/ 

", 

/ 

16, 

/ 

40, 

/ 

160, 

/ 

0L, 

/ 

0, 

/ 

01, 

/ 

0L, 

/* 

Paint, 

/' 

0,0,0,0, 

/' 

-1L, 

/ 

0); 

/■ 

1  Record  size 
>  Frame   ddaO 
'  Ptr  to  title 

•  RefCon 

'  Full  size  (  0  - 
'  Color  Table  Ptr 
'  Vertical  Origin  */ 
'  Horizontal  Origin 

'  Data  area  night  */ 
'  Data  area  width  */ 
'  Max  cont  height  */ 
'  max  cont  width  */ 
'  pixels  to  scroll  vert 
'  pixels  to  scroll  horz 
'  pixels  to  page  vert 
1  pixels  to  page  horz 
'   info  bar  string 

•  info  bar  height 
'  def  proc  ptr 

info  bar  def  proc 
r  Content  def  proc 
'  size/pos  of  content 
1  plane  of  window 
'  Wind  Rec  add 


V 
V 
*/ 
V 
default)*/ 
*/ 


*/ 
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extern  FilelORec  ReadParams; 
extern  FilelORec  WriteParams; 

Rect  ISizPos  =  (20,10,80,350); 

/* 

typedef  struct  FontlnfoRecord  ( 

Integer  ascent; 

Integer  descent; 

Integer  widMax; 

Integer  leading; 
)  FontlnfoRecord,  *FontInfoRecPtr,  **FontInfoRecHndl; 
*/ 


FontlnfoRecord  FIRecord; 

SFReplyRec  MyReply  -  (0,0,0,"  ","  "); 

extern  OpenRec  MyOpenParams; 


char  Prornptl    []    =   "\pLoad  which  picture:"; 
char  Prompt2    []    -   "\pSave  which  picture:"; 

int  Wxoffset  =  20; 
int  Wyoffset  =  12; 

handle  PicHandle; 

extern  boolean  OpenWindowO  ; 
extern  boolean  AskUserO; 
extern  boolean  LoadltUp () ; 
extern  boolean  DoTheOpenO; 

GrafPortPtr  WhichWindow; 

GrafPortPtr  WindowList [16] ; 

int  vlndex; 

GrafPortPtr  vTable[16]; 

int  Windex  -  0; 


/*  OpenRec  ( 

int  openRefNum; 
ptr  openPathname; 
long  iOBuffer; 
}  */ 


/*  handle  to  picture  data  */ 
/*  to  add  window  to  menu  */ 

/*  current  window  handle  */ 

/*  list  of  window  handles  */ 

/*  index  to:    |       */ 
/*  \  /      */ 

/*  list  of  what  was  visible  */ 

/*  index  to  next  avail  wind  id*/ 


Loclnfo  Srclnfo640  -  ( 


); 


0x80, 

/*  used  to  be  byte  here  */ 

0L, 

160, 

(0,0,200,640) 


Rect  SrcRect640    -  (0,0,200,640); 


/* 


I*   Now  the  real  stuff 

/*  Procedure  to  Close  windows,  we  close  them  from  the  back. 
Things  move  faster  this  way. 
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HideAllWindows  () 
{ 

vlndex  =  0;  /*  init  index  */ 

if  (vTable  [vlndex]  =  FrontWindowO  )         /*at  least  one  window  */ 
( 
for  (vlndex; vTable [vlndex  +  1]  =  GetNextWindow (vTable [vlndex] ) ;vlndex++) ; 
for  (vlndex;vlndex  >=  0;vlndex — ) 
HideWindow (vTable [vlndex] ) ; 
1 
I 


/*  DoOpenltem: 

1)  Make  sure  that  there  aren't  too  many  windows  open  already; 

2)  Call  OpenWindow  to  let  the  user  see  it;  if  successful, 

3)  Call  AddToMenu  to  add  the  name  to  the  windows  menu  list. 


V 


DoOpenltem  () 
I 

if    (Windex  =-  NUM_WINDOWS) 

ManyWindDialog    (); 
else 

if    (OpenWindow    ()) 
AddToMenu    ()  ; 


) 


/*  OpenWindow: 

1)  Calls  SFGetFile  to  get  name  of  file  to  display  in  window 
(or  the  dialog  to  select  font  if  needed) 

2)  Gets  memory  for,  and  loads  the  picture/font  data  into  memory 

3)  Allocates  a  new  window 

a) puts  handle  to  MyWindowInfo  in  WrefCon 

b)  note  that  wContDefProc  is  set  to  "Paint" 

c)  for  fonts  WContDefProc  is  set  to  "DispFontWindow" 

The  definition  of  MyWindowInfo  is  global  data. 
*/ 


boolean  OpenWindow!) 
1 

if  ((TheEvent.wmTaskData  £  OxFFFF)  --  ShowFontID) 
( 

if  (DoChooseFont  ()  ) 
if  (DoTheOpen  ()  ) 

return  (TRUE); 
else 

return  (FALSE) ; 
else 

return  (FALSE) ; 
1 

else 
( 

if  (AskUserO) 

return (TRUE) ; 
else 

return (FALSE) ; 


) 


I 
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/* 

typedef  struct  SFReplyRec  { 
Boolean     good; 
Word     flleType; 
Word     auxFileType; 
char     filename [16]; 
char     f ul lPathname [129]; 
}  SFReplyRec,   *SFReplyRecPtr  ; 
/ 

boolean  AskUser(> 
f 

f  fGmFnle,(2°'  *°'  PromPtl.  OpenFllter,  OL,  iMyReply)  ; 
if  (MyReply.good)  w-xi  i 

if  (LoadltUp(J) 

return (TRUE) ; 
else 

return (FALSE) ; 
else 

return (FALSE); 

boolean  LoadltUpO 
1 

WaitCursor  (); 

PicHandle  =  NewHandle(0x8O00L,MyID,0,0L)  • 
if  (_toolErr) 

return  (FALSE)  ; 
else 

( 

ReadParams.dataBuffer  -   *PicHandle- 
HLock (PicHandle) ; 
if  (DoTheOpenf) ) 

return (TRUE); 
else 

return (FALSE)  ; 
) 
) 


boolean  DoTheOpenO 

int  auxl,aux2; 
ptr  aux; 

boolean  lOError  -  FALSE; 

int  i; 

/*  there  is  always  a  need  */ 
long  FIDAux; 

MyDataHandle  =  (DataRecHandle)NewHandle ( (long,  (sizeof (DataRec, , 

MyWindow.wRefCon  -  (long,  MyDataHandle;    MyID' °Xc000<  °^ 

if  (_toolErr, 

return (FALSE,  ; 
else 
{ 

RefPtr  -  *MyDataHandle; 
HLock (MyWindow.wRefCon) ; 

/*  The  assumption  is  that  the  window  is  for  a  picture  (not  a  font,  V 

R^tnrdO!;WFCLngD=f0-OC  =  <""*«£»?  *"*! 

9   u'  /*  picture  flag  */ 
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if    ((TheEvent.wmTaskData   &    Oxffff)    ==  ShowFontID)      /*   were  we  right?    */ 
( 

RefPtr  ->   Flag   -  Oxl    |    MonoFlag;      /*        No!    so  change  */ 

PicHandle  =    (handle)     ( (DesiredFont. famNum)    + 

(DesiredFont.fontSize     *  0x1000000)    + 
(DesiredFont. font  Style    *   0x10000)); 
/*   everything  to   font        */ 

/*   display  */ 

MyWindow.wContDefProc  =    (VoidProcPtr)    DispFontWindow; 

) 

else 

( 

MyOpenParams.openPathname  =  MyReply . fullPathname; 

if  (!  (LoadOneO)) 
IOError  =  TRUE; 
)  /*  end  of  picture  stuff  */ 

if  (IOError) 
( 
DisposeHandle (MyWindow.wRefCon) ; 
DisposeHandle (PicHandle)  ; 
return (FALSE) ; 
! 
else 
1 
RefPtr  ->  PicHand  -  PicHandle; 
RefPtr  ->  Blank  -  0x20; 
MyWindow.wTitle  -  RefPtr  ->  Str; 

If  (! (MyReply. filename[0]  <-  MaxNameSize) ) 

MyReply. filename [0]  =  MaxNameSize; 
for  (i=MyReply.filename[0];i>=0;i— > 

RefPtr  ->  Str[i]  =  MyReply . filename [i]  ; 

MyWindow.wDataW  =  640; 

MyWindow.wMaxW  =  640; 

ISizPos.h2  -  350; 

MyWindow.wDataH  -  200;  /*  in  case  is  a  picture  */ 

SetPort  (OrigPort); 

if  ((TheEvent.wmTaskData  &  OxFFFF)  ==  ShowFontID) 
{ 
FIDAux  -  GetFontlDO; 

InstallFont (PicHandle, 0) ; 

GetFontlnfo  (sFIRecord) ; 

MyWindow.wDataH  = 

( (FIRecord. ascent  +  FIRecord. descent)  *  (NumLines  +  1) ) ; 

FindMaxWidthO; 

InstallFont (FIDAux,  0) ; 
} 

/*  windows  have  to  offset  evenly  */ 
MyWindow.wPosition.vl  =  Wyof f set+ISizPos.vl; 
MyWindow.wPosition.hl  -  Wxoffset+ISizPos.hl; 
MyWindow.wPosition.v2  =  Wyof f set+ISizPos.v2; 
MyWindow.wPosition.h2  -  Wxof f set+ISizPos.h2; 

Wxoffset  +-  20; 

if  ((Wyoffset  +-  12)  >  120) 
Wyoffset  =12; 
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WhichWindow  =  NewWindow (SMyWindow) ; 

SetPort  (OrigPort); 

HUnlock (PicHandle) ; 

SetOriginMask (OxFFFE, WhichWindow) ; 

InitCursor  ()  ; 

return(TRUE);  /*   finally!    */ 


} 


) 


void  DoSaveltemO 

I 

DataRecHandle  AuxHandle; 

Pointer  AuxPtr; 

int   i; 

WhichWindow  =  FrontWindow  () ; 

AuxHandle  -  (DataRecHandle)  GetWRefCon (WhichWindow) ; 

RefPtr  =  *AuxHandle; 
HLock (AuxHandle) ; 


if  (! (RefPtr  ->  Flag))  /*  Save  only  type  0  windows  */ 

1 

MyOpenParams.openPathname  =  GetWTitle  (WhichWindow)  ; 
SFPutFile  (20, 20, Prompt 2, MyOpenParams.openPathname, 15, SMyReply) ; 
if  (MyReply.good)  /*  <>  0  — >  OK  to  save  it  */ 

1 

WaitCursor  ()  ; 

PicHandle  -  RefPtr  ->  PicHand; 

WriteParams.dataBuffer  -  "PicHandle; 

HLock (PicHandle); 

MyOpenParams.openPathname  =  MyReply.fullPathname; 

SaveOneO;  /*  save  the  picture  */ 

for  (i  =  MyReply.filename[0];i  >=  0;  i — ) 

RefPtr  ->  str[i]  =  MyReply. filename [i] ; 
SetWTitle (RefPtr  ->  Str, WhichWindow) ; 
HUnlock (PicHandle) ; 
CalcMenuSize (0L,WindowsMenuID) ; 
InitCursor  ()  ; 
) 
) 


) 


/*  This  routine  finds  out  how  wide  the  window  should  be  for  the 

current  font 
*/ 

FindMaxWidthO 

( 

int  tempFlags; 
int  LineCounter; 
int  aux; 
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MyWindow.wDataW  =  0; 
tempFlags  =  GetFontFlags  ()  ; 
SetFontFlags ( (RefPtr  ->  Flag  »  1)    &  1); 

for    (LineCounter  =  l;LineCounter  <  NumLines; LineCounter++) 
if   (    (aux  =  StringWidth(LineTable [LineCounter] ))    >  MyWindow.wDataW) 
MyWindow.wDataW  -  aux; 
MyWindow.wDataW  +=  10; 

SetFontFlags (tempFlags) ;  /*  put    flags  back   */ 

I 

/*  Close  a  window  and  dispose  of  extra-data    (in  WRefCom) 

and  remove  it   from  window  list 
V 

DoCloseltemO 

I 

DataRecHandle  tempHand2; 

DataRecPtr  tempPtr2; 

int  IDDelete; 
int  Counter; 
int  IDStart; 
int  IDNew; 

if  (WhichWindow  =  FrontWindowO  ) 
1 

CloseNDAByWinPtr (WhichWindow) ;    /*  if  it's  a  sys  wind  this  is  enough*/ 
if  (_toolErr)  /*  error  means  wasn't  a  system  window  */ 

( 
tempHand2  =  (DataRecHandle)  GetWRefCon (WhichWindow) ; 
tempPtr2  -  *tempHand2;  /*  deref    */ 

HLock(tempHand2) ;  /*  and  lock  it  */ 

PicHandle  =  tempPtr2  ->  PicHand;  /*  handle  to  get  rid  of*/ 

if  (tempPtr2  ->  Flag)  /*  ~0  -->  font  */ 

PicHandle  -  NIL;  /*  so,  don't  dispose    */ 

IDDelete  =  AdjWindO  +  300;         /*  take  it  out  of  list  */ 
if  (Windex  ™  1)  /*  one  wind  is  special  case  */ 

( 

InsertMItem(origltem,0,WindowsMenuID) ;  /*  no  windows  message*/ 
SetMenuFlag (0x0080, WindowsMenuID) ;      /*  disable  windows  */ 
DrawMenuBar  ()  ; 

Wxoffset  =  20;  /*  reset  start  */ 

Wyoffset  =  12;  /*  for  window  sizing  */ 

) 

DeleteMItem(IDDelete) ;  /*  off  the  menu  */ 

Windex — ; 


if  (Counter  =  Windex) 
( 

IDStart  =  300; 

IDNew  -  300;  /*  starting  point  */ 

while  (Counter) 
I 

if  (IDStart  !-  IDDelete) 
I 

SetMItemID (IDNew,  IDStart) ; 
IDNew++; 
Counter — ; 
) 
IDStart++; 
) 
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) 
) 


CalcMenuSize(OL,WindowsMemiID)  • 
DisposeHandle  <tGmpHand2) ■ 
if    (PicHandle) 

DisposeHandle (PicHandle) ; 
CloseWlndow(WhlchWlndow) ; 


Adjwindf) 

{ 

int  IDCounter, i,y; 

i  =  Wlndex  -1; 
IDCounter  =  i; 

«hile_<!(,whichWindow  „  wlndowLlst[1])  ,,  ±  <  0)J 
y  -  i; 
while  (!(y  =_  IDCounter)) 

WindowList [y]  =  WindowList F  y  +  i,. 
y++;  *         iJ' 

) 

return (i); 
) 

"  draw  tPhre°Cpidctuerr S  C"""d  *«  ^  -*«  *-l-  ls  tlme  to 
*/ 

Paint  () 

( 

DataRecHandle  auxHandle; 

GrafPortPtr  auxPtr; 

DataRecPtr  DataPtr; 

auxPtr  =  GetPort  ()  • 

auxHandle  =  (DataRecHandle)  GetWRPft-on  ,  /l9St  current  P°"  */ 

DataPtr  =  'auxHandle;     '  GetWRefCon  (»™Ptr) ;       /.  handle  to  data 

HLock (auxHandle) ; 

Paintlt, DataPtr  ->PicHand);      ,.  (nandle  t)    t/ 
HUnlock (auxHandle) ; 

;;  ^iiL^^ndi:  t^:Sete  the  p—  •*«  it 

Paintlt (Painthand) 
handle  Painthand; 

( 

Ptr  auxPtr2; 

auxPtr2  -  *Painthand; 

/*  deref  */ 
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HLock  (Painthand)  ; 

SrcInfo640.ptrToPixImage  =  auxPtr2; 
PPToPort (sSrdnfo640, sSrcRect640, 0, 0, 0) ; 
HUnlock (Painthand); 


DoGoAway  () 
HideWlndow  (TheEvent  .wraTaskData) ; 


DoWindowf) 

SelectWindow  (WhichWindow) ; 
ShowWindow  (WhichWindow)  ; 


pascal   int  OpenFilter    (DirEntry) 

ptr  DirEntry; 

/*  Filter  function   called  by  the   Standard  File  Operations'    SFGetFile 
dialog  to  determine  whether  a   filename   should  be  dimmed  or  not.    */ 

I 

if  ((*  (DirEntry  +  0x10)  s  OxOOFF)  —  OxCl)   /*  Type  $C1:  picture  file  */ 
return  (2);  /*  ...  so  it's  undimmed.   */ 

else 

return  (1);  /*  Else  show  it  dimmed.   */ 

1 
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DIALOG.CC  (dialog  boxes) 

+ 

* 

HodgePodge:   An  example  Apple  IIGS  Desktop  application        * 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Source  file  DIALOG.CC  —  Dialogs  and  error  trapping 


****************** 


******************* ************* 


***********/ 


♦include 

<types.h> 

♦include 

<quickdraw.h> 

♦include 

<gdaux.h> 

♦include 

<memory . h> 

♦include 

<dialog.h> 

♦include 

<prodos . h> 

♦include 

<texttool.h> 

♦include 

<stdfile.h> 

♦include 

<window.h> 

♦include 

<locator.h> 

♦include 

<intmath.h> 

♦include 

<misctool.h> 

♦include 

"hp.h" 

extern  int 

toolErr; 

extern  int 

MylD; 

extern  GrafPortPtr 

OrigPort; 

GrafPortPtr 

MsgWindPtr; 

/*  Data  structure  for  "About  HodgePodge..."  dialog  box:  V 

static  char  OKStr  []  =  "\pOK"; 

Rect  DRect  -  (20,190,192,450); 

Rect  ApplelconRect   =    (135,20,0,0); 
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char  Applelcon640[]  =  {0x00,0x00,0x00,0x00,0x22,0x00,0x40,0x00, 

0x00, 0x00, 0x00,  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
OxOf ,  Oxf f ,  Oxf f ,  Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf 0, 
OxOf ,  0x00, 0x00,  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  0x00,  0x00, 0x00,  Oxf 0, 
OxOf ,OxOf ,  Oxf f ,  Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f ,  Oxf f , OxfO, Oxf 0, 
OxOf,  OxOf, Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf 8, 0x8f ,  Oxf f , Oxf f , Oxf 0,  Oxf 0, 
OxOf , OxOf , Oxf f ,  Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , Oxf 8, 0x88, 0x8f, Oxf f ,  Oxf f , OxfO, OxfO, 
OxOf, OxOf,  Oxf f ,  Oxf f ,  Oxf f , Oxf f , Oxf f , Oxf f , Oxf f , 0x88, 0x88, 0x8f, Oxf f , Oxf f , Oxf 0, Oxf 0, 
OxOf, OxOf ,  Oxf f ,  Oxf f , Oxff , Oxff , Oxf f , Oxff ,0xf8, 0x88, 0x88, Oxf f,  Oxf f ,  Oxf f,  OxfO,  Oxf 0, 
OxOf , OxOf ,  Oxff,  Oxff, Oxff, Oxff, Oxff, Oxff, 0x88, 0x88, 0x88, Oxf f, Oxff, Oxff, Oxf 0, Oxf 0, 
OxOf , OxOf , Oxff,  Oxff, Oxff, Oxff, Oxff, Oxff, 0x88, 0x88,  0x8f , Oxff, Oxff,  Oxff,  OxfO,  OxfO, 
OxOf , OxOf , Oxff,  Oxff, Oxff, Oxff, Oxff, Oxff, 0x88, 0x88, Oxff, Oxff, Oxff, Oxff, OxfO, OxfO, 
OxOf,  OxOf,  Oxff,  Oxff,  Oxf  8,  0x88,  0x8f,  Oxff,  0x88,  Oxf  f,  0x88, 0x88,  Oxf  f,  Oxff,  Oxf  0,  Oxf  0, 
OxOf , OxOf , Oxff,  Oxf 8, 0x88, 0x88, 0x88, 0x8f , Oxff, 0x88, 0x88, 0x88, 0x88,  Oxff, OxfO, OxfO, 
OxOf, OxOf,  Oxff,  0x88, 0x88,  0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88, 0x88,  0x8f , Oxf 0, Oxf 0, 
OxOf,  OxOf, Oxf e, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxef , Oxff, OxfO , OxfO, 
OxOf,  OxOf,  Oxf e,  Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxff, Oxff, Oxf 0, Oxf 0, 
OxOf,  OxOf, Oxf e, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee, Oxee,  Oxee,  Oxef, Oxff,  Oxff,  OxfO ,  OxfO, 
OxOf,  OxOf,  Oxf  6,  0x66, 0x66,  0x66,  0x66,  0x66,  0x66,  0x66,  0x66, 0x6f ,  Oxff,  Oxff,  Oxf  0,  Oxf  0, 
OxOf ,  OxOf , Oxf 6, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x66, 0x6f , Oxff,  Oxff,  OxfO, OxfO, 
OxOf,  OxOf,  Oxf  6,  0x66, 0x66,  0x66,  0x66,  0x66, 0x66,  0x66,  0x66, 0x6f ,  Oxff,  Oxff,  Oxf  0,  Oxf  0, 
OxOf,  OxOf,  Oxf 4,  0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, Oxff, Oxff, OxfO, OxfO, 
OxOf,  OxOf, Oxf 4, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, Ox4f, Oxff, Oxf 0, Oxf 0, 
OxOf,  OxOf, Oxff,  0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x44, 0x4f, OxfO, OxfO, 
OxOf,  OxOf, Oxff, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x5f , Oxf 0, Oxf 0, 
OxOf , OxOf ,  Oxff,  0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55,  0x5f , OxfO, OxfO, 
OxOf , OxOf , Oxff, Oxf 5, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55,  0x55,  Oxff, Oxf 0,  Oxf 0, 
OxOf, OxOf, Oxff,  Oxf 1,0x11, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll,  Oxff, OxfO, OxfO, 
OxOf , OxOf ,  Oxff,  Oxff, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxll, Oxlf, Oxff, Oxf 0, Oxf 0, 
OxOf,  OxOf, Oxff,  Oxff, Oxfl, Oxll, Oxll, Oxlf, Oxff, Oxll, Oxll, Oxll,  Oxf f,  Oxff,  OxfO,  OxfO, 
OxOf,  OxOf, Oxff,  Oxff, OxfF, Oxll, Oxll, Oxff, Oxff, Oxfl, Oxll, OxlF, Oxff, Oxff, OxfO, Oxf 0, 
OxOf,  OxOf, Oxff, Oxff, Oxff, Oxff, Oxff, Oxff, Oxff, Oxff,  Oxff, Oxff, Oxff,  Oxff,  OxfO ,  OxfO, 
OxOf  ,0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, Oxf 0, 
OxOf,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  Oxff,  OxfO, 
0x00, 0x00, 0x00,  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 


Rect  TextlRect  =  (12,4,200,256); 

/*  This  Is  L0NGSTATTEXT2-formatted  type  text:  */ 

char  Textl  []  =  "\1J\1\0\ 

\1S\010\0\ 

Hodgepodge  In  C\ 

\r\ 

\r\ 

\1S\0\0\ 

A  potpourri  of  routines  that  demonstrates  many  \ 

features  of  the  Apple  IIGS  tools. \ 

\r\ 

\r\ 

By  the  Apple   IIGS  Development   Team\ 
f         \r\ 
I         \r\ 

Copyright  Apple  Computer,    Inc.,    1986-1987, \ 

\r\ 

All  rights  reserved\ 
!  \r\ 

v4.0       October  1987"; 


Rect  ButtonRect   =    {153,180,0,0); 
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/*  Dialog  Template  data  structure  for  "Please  wait  while  ..."  dialog:  */ 

char  PlsWtMsg  []  -  "\pPlease  wait  while  we  set  things  up."; 

ItemTemplate  PlsWtltem  -   (1348, 

19,70,200,640, 

statText, 

PlsWtMsg, 

0, 

0, 

NULL); 

DialogTemplate  PlsWtTemp  =  (30,120,80,520, 

true, 
NULL, 

SPlsWtltem, 
NULL); 


/*  Alert  Template  data  structure  for  too  many  windows  and  disk  error  alerts:  */ 

ItemTemplate  OurAlertlteml  -  (1, 

25,320,0,0, 

buttonltem, 

OKStr, 

0, 

0, 

NULL); 

ItemTemplate  OurAlertItem2  -  (1348, 

11,72,200,640, 

statText, 

NULL,  /*  ItemDescr  —  will  fill  it  in  */ 

0, 

0, 

NULL); 

AlertTemplate  OurAlertTemp  -  (30,120,80,520, 

6666, 

0x80, 0x80, 0x80, 0x80, 
SOurAlertlteml, 
£OurAlertItem2, 
NULL); 


CheckToolError  (Where) 

/*  CheckToolError  checks  to  see  if  the  last  tool  call  completed  successfully. 
If  so,  then  it  just  returns.   If  not,  we  crash  using  the  System  Death 
Handler  (bouncing  apple) .  */ 

int  Where; 

( 

static  char  DeathMsg    [J    =   "\p  At    $XXXX;    Could  not   handle  error  $■•■ 
int     ToolErrorSave; 
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ToolErrorSave  =  _toolErr; 

if  (ToolErrorSave) 

I 

Int2Hex     (Where,  DeathMsg  +  6,4); 

SysFailMgr  (ToolErrorSave, DeathMsg) ; 


boolean  CheckDiskError  (Where) 

/*  This  routine  checks  if  the  last  ProDOS  operation  caused  an  error.   If  so, 
then  we  change  the  cursor  to  the  arrow  cursor,  put  up  a  stop  alert  dialog 
box  with  the  text  of  the  error  message,  which  then  waits  for  the  user's 
OK  click,  and  then  change  the  cursor  back  to  the  wristwatch.   If  there 
was  no  disk  error,  then  we  do  nothing.  We  also  return  TRUE  or  FALSE 
depending  on  whether  an  error  actually  occurred  or  not.  */ 

lnt  Where; 


int  DiskErrNum; 

DiskErrNum  =  _toolErr;  /*   Save  this   first    */ 

if    (DiskErrNum) 

( 

0urAlertItem2.itemDescr  =   "\pDisk  Error  $XXXX  occurred  at  SXXXX."; 
Int2Hex    (DiskErrNum,  /*    put  ASCII      */ 

0urAlertItem2.itemDescr  +   13, 
4); 
Int2Hex    (Where,  /*   put  ASCII     */ 

0urAlertItem2.itemDescr  +  31, 

4); 

InitCursor  () ;  /*  Set  arrow  cursor     */ 

StopAlert   (SOurAlertTemp, NULL) ;  /*  Draw  dialog  &  wait   */ 

/*  Do  not  restore  watch  cursor  */ 

} 

return  (DiskErrNum);  /*  Assign  function  result  */ 


ManyWindDialog  () 

/*  Displays  caution  alert  dialog  with  a  message  about  no  more  windows 
being  allowed  open.  Handles  mouse  events  until  OK  button  is  clicked. 
Then  the  dialog  box  is  removed  and  we  return.  */ 


( 


0urAlertItem2.itemDescr  =  "\pNo  more  windows,    please.";        /*   Set   string  */ 
CautionAlert      (sOurAlertTemp,NULL) ;  /*  Do  draw,   wait,    undraw.    */ 


DoAboutltem    () 

/*  Function  DoAboutltem  shows  how  to  build  a  dialog  box  manually.    */ 

I 

handle  ApplelconH; 

GrafPortPtr  MdialogPtr; 


ApplelconH  -  NewHandle    (552L,MyID,0,0L) ;  /* 

CheckToolError                    (50) ;  /* 

HLock                                          (ApplelconH) ;  /* 

PtrToHand             (Applelcon640, ApplelconH, 552L) ;  /* 


Allocate  memory  */ 
Hope  it  was  ok  */ 
Freeze  handle  */ 
Move  icon  image  */ 
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) 


MdialogPtr  =  NewModalDialog  (sDRect, TRUE, OL) ;    /*  Draw  dialog  box  V 

/*  Install  and  draw  Items  In  the  dialog  box-  */ 

NewDItem  (MdialogPtr, 1, SButtonRect, buttonltem, OKStr, 0, 0,NULL) ■ 

NewDItem  (MdialogPtr, 3,  sApplelconRect, iconltem+itemDisable, 

ApplelconH, 0, 0, OL) ; 
NewDItem  (MdialogPtr, 4, STextlRect, longStatText2+itemDisable,Textl 

sizeof  (Textl)  -  1,0,0L); 

ModalDialog    (NULL) ;  /.  Track  the  mouse  inside 

CloseDialog    MdialogPtr);     /.  Remove  the  box  from  the  screen  V 
DisposeHandle  (ApplelconH) ;     /*  Deallocate  memory  ./ 


/*  ShowPleaseWait  /  HidePleaseWait  V 

/*  Brings  up  a  window  and  puts  a  message  on  it 
witout  waiting  for  Update  Event  */ 

ShowPleaseWait  () 
( 

OrigPort   =  GetPort  (); 

MsgWindPtr  =  GetNewModalDialog  (SPlsWtTemp) ; 


BeginUpdate  (MsgWindPtr) 

DrawDialog  (MsgWindPtr) 

EndUpdate  (MsgWindPtr) 
) 


HidePleaseWait  () 
( 

CloseDialog (MsgWindPtr) ; 

SetPort (OrigPort) ; 
) 


/*  begin  Update  process  */ 


Mount BootDisk  () 

'*   ™^M°tDi8lt  lsv.CaUed  ^never  the  application  requires 

something  from  the  boot  volume  and  it  is  not  online        */ 

( 

static   char  PromptStr  []  =        "VpPlease   insert  the  disk", 

OKStr  []  =        »\pOK», 

CancelStr  [)  =  "\pShut  Down", 

VolStr  [256]; 

static  PathNameRec     GBVParams  =  (    VolStr, NULL   ); 

GET_B00T_VOL    (SGBVParams) ; 

return    (TLMountVolume    (174, 30, PromptStr, VolStr,  OKStr,  CancelStr) ) ; 
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FONT.CC  (fonts) 


Hodgepodge:  An  example  Apple  IIGS  Desktop  application       * 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Source  file  FONT.CC  —  Choosing  font,  font  window  defproc       * 

* 
************************************  *********t1,t),i,i,i,i,i,i,i,1,ti,),ti,tirtti,iIi!^ 

♦include  <types.h> 
•include  <qulckdraw.h> 
♦include  <font.h> 
♦include  <intmath.h> 
♦include  <stdfile.h> 
♦include  <window.h> 
♦include  <memory.h> 
♦include  <menu.h> 
♦include  <texttool.h> 
♦include   "hp.h" 

extern  SFReplyRec  MyReply; 

/* 

typedef  struct   SFReplyRec     ( 

Boolean  good; 

Word  fileType; 

Word  auxFileType; 

char  filename [16]; 

char  fullPathname[129]; 

)   SFReplyRec,      *SFReplyRecPtr  ; 

extern  int  _toolErr; 
ptr  FontWlnPtr; 

/* 

typedef  struct  Font ID   ( 

Word  famNum; 

Byte  fontstyle; 

Byte  fontSize; 

(  FontID,  *FontIDPtr,  **FontIDHndl; 
V 

FontID  DesiredFont  -  (  0xfffe,00,0x08); 

int  MonoFlag  -  0; 

/* 

typedef  struct  FontlnfoRecord  ( 

integer     ascent; 

integer     descent; 

integer     widMax; 

Integer     leading; 
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)  FontlnfoRecord,  *FontInfoRecPtr,  **FontInfoRecHndl; 
*/ 

FontlnfoRecord  CurrFont; 

int  CurrHeight, LineCounter; 

/* 

typedef  struct  Point  f 

Integer   v; 

Integer   h; 

)  Point,  *PointPtr,  **PointHndl; 
*/ 

Point  CurrPos; 

char  Line0[30]  -  (0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,   /*   Namelength  +  1   */ 
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0);  /*  +  4  for  size  info  */ 
char  Linel[]  =  "\0"; 

char  Line2[]  -  "\pThe  quick  brown  fox  jumps  over  the  lazy  dog."; 
char  Line3[)  -  "\pShe  sells  sea  shells  down  by  the  sea  shore."; 
char  Line4[]  -  "\0"; 

char  Line5[]  =  (32, 

0,  1,  2,  3,  4,  5,  6,  7,  8,  9,10,11,12,13,14,15, 
16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 25, 27, 28, 28, 30, 31,0 (; 

char  Line6[)  -  (32, 

32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47, 
48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,  63,0); 

char  Line7[]  =  (32, 

64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79, 
80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,0); 

char  Line8[]  =  (32, 

96,  97,  98,  99,100,101,102,103,104,405,106,107,108,109,110,111, 
112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127, 
0); 

char  Line9[]  =  (32, 

128,129,130,131,132,133,134,135,136,137,138,139,140,141,14  2,143, 
144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159, 

0); 

char  Linel0[]=  (32, 

160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175, 
176,177,178,179,180,182,182,183,184,185,186,187,188,189,190,191, 
0); 

char  Linell[]=  (32, 

192,193,194,195,196,197,198,199,200,201,202,203,204,205,206,207, 
208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223, 

0); 

char  Linel2[)=  (32, 

224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239, 

240,241,242,243,244,245,246,247,248,249,250,251,252,253,254,255, 

0); 

char  *LineTable[]  -  (Line0,Linel, Line2,Line3,  Line4,Line5,Line6,Line7, 
Line8,Line9,LinelO,Linell,Linel2); 

char  ProMsg[32]  =  "==Display  Font  as  Proportional\r"; 
char  MonoMsg[31]=  "--Display  Font  as  Mono-spaced\r"; 
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DoChooseFont  () 

I 

int  whocares; 

GrafPortPtr  oldPort; 

int  tempPort[85];  /*  port  size  in  bytes  /  2  */ 

/* 

typedef  struct  FontID   ( 

Word  famNum; 

Byte  fontstyle; 

Byte  fontsize; 

}  FontID,  *FontIDPtr,  **FontIDHndl; 
V 

long  tempFont; 

oldPort  =  GetPort  ()  ; 

OpenPort (tempPort) ; 

if  (tempFont  =  ChooseFont (DesiredFont,0) )  /*  font  changed  */ 

DesiredFont. famNum  -  (Word) (tempFont  &  Oxf f ff ) ; 

DesiredFont. fontstyle  -  (Byte)  ( (tempFont  »  16  )  I   Oxf f ) ; 

DesiredFont. fontsize  -  (Byte)  (tempFont  »  24); 

whocares  -   GetFamlnfo (DesiredFont. famNum, 

MyReply. filename);/*  ignore  result  */ 

Int2Dec (DesiredFont. fontsize,    /*  size  of  font  */ 

( (MyReply. filename) + (MyReply. filename [0 ]) +1) ,/*  position*/ 
*»  /*  length  of  result  */ 

°>''  /*  not  signed  */ 

MyReply. filename[0]  +-4;  /*  new  legth    */ 

ClosePort (tempPort) ; 

SetPort (oldPort); 

return (TRUE);  /*  new  stuff  */ 

else 
I 

ClosePort (tempPort) ; 

SetPort  (oldPort); 

return (FALSE);  /*  No  change  */ 

) 

DispFontWindowO 

I 

FontID  fontld;  /*  Dont  need  it   */ 

FDataRecHandle  FontHand; 
FDataRecPtr  FontPtr; 

GrafPortPtr  tempPort  ,- 

tempPort  -  GetPort () ;  /*  get   curr  port   */ 

FontHand  -=    (FDataRecHandle)    GetWRefCon  (tempPort ) ;   /*  get   handle  to  data  */ 
FontPtr  -  *FontHand;  /*  dereference  */ 

HLock (FontHand) ; 

ShowFont (FontPtr  ->  FID, FontPtr) ; 
HUnlock (FontHand) ; 
1 

ShowFont (fontld,  FontPtr) 

FontID  fontld; 
FDataRecPtr  FontPtr; 
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( 

word  tempFlags; 

InstallFont (fontld,  0)  ; 

GetFontlnfo (SCurrFont)  ; 

CurrHeight  =  CurrFont .ascent  +  CurrFont. descent  +  CurrFont. leading- 

MoveTo(u,0);  /.   start   pen  ^^^   *, 

GetFamInfo(fontId.famNum,LineO) ;  /*    ignore   result   */ 

Int2Dec  (fontld. fontSize,  /*  size  of  font     */ 

(Line0)+Line0[0]+1,  /*  pointer  to  end*/ 

'  /*   length  of  result   */ 

0)'  /*   not    signed   */ 

LineO [0]    +=4;  /*  new  iengtn  ./ 

tempFlags  -  GetFontFlags () ; 

SetFontFlags((((FontPtr  ->   Flag))    »   1)    s   1); 

for    (LineCounter  -  0;LineCounter  <  NumLines;LineCounter++) 
I 

GetPen(SCurrPos) ; 

MoveTo (5, CurrHeight   +  CurrPos.v);  /*   reset  x  and  y  */ 

Drawstring (LineTable [LineCounter] ) ; 
J 

SetFontFlags  (tempFlags) ; 
) 

DoSetMonof) 

I 

if  (MonoFlag  A=0x02) 

SetMItem(ProMsg,MonoID) ; 
else 

SetMItem(MonoMsg,MonoID)  ; 
) 
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PRINT.CC  (printing) 


*  * 

*  Hodgepodge:   An  example  Apple  IIGS  Desktop  application        * 


Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


♦  Source  file  PRINT.CC  —  Printing  stuff  * 

♦  * 

♦  include  <types.h> 

♦  include  <memory.h> 

♦  include  <quickdraw.h> 

♦  include  <window.h> 
♦include  <print.h> 

♦  include  <qdaux.h> 
♦include  <font.h> 
♦include  "hp.h" 

extern  int  MylD; 

GrafPortPtr  WindowToPrint    -  NIL; 

handle  PrintRecord  =  NIL; 

GrafPortPtr  PrintPort; 

/*  Coose  Printer  Item  handler  */ 

DoChooserltemO 
( 

PrChooser  ()  ; 
) 

/*  Routine  to  handle  page  setup  item  */ 

DoSetUpItemO 
( 

if  (!  (PrintRecord) ) 
SetUpDefault  ()  ; 

PrStlDialog (PrintRecord) ; 
1 

/*  routine  to  create  default  print  record  */ 

SetUpDefault  () 
( 

PrintRecord  -  NewHandle (140L, My ID, 0x8010, OL) ; 

PrDefault (PrintRecord) ; 
) 

/*  Now  the  menu  item  "Print"  item  */ 
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Mri-tl-emO 

if    [W<n<ioWioL'rint  -  TYrjiiWi-dowfit  f    \y.  th^ro  a  window  to  prim?  *,' 

if    (i  [SI  kLl.HciOTZQ)  J 

$e«pr.e*ayltH>; 
it    (P'.Tii'nrjiilsqiieTintSeT&rUJJ 

HdlLCu-ncrO  ■ 

rrtn-Poit  -  P^wnDoc  (Fr tjv; Record,  ULJ; 

f.rOpenFaa.sJPrintycrt,  ai.)  ,- 

Draw 1'opWi  :-.;'J<:w  ( )  j 

DrCisi&Paca  IrriL-.tFO!  I  :■; 

l?rCiOin:!;c)i:(vTi^rrort)  ; 

Irrt^FiLt  (Printkaco:;^,  m.,  3T,|  ■ 

I^itCujjirtri)  ; 


D r ^"{lTTrfindSW  i  I 

I 

Oat*&*fiKiaeU.e  Thi:n«r;<jji  -NIL:  /'  we  use  jltoSitly  di'lrvr-L    >■/ 

n^BscE-tr  aassftr;  / *  B ,. r „„, . u rc,  f or  p.£, u ee s       ^ 

n)nU-*ec::ai-u!ic  jtotsaagfls;  /„  i:,>d  We  im,^  ^ 

EastaReoSU*  font  Pt  r ; 

'i'JuafierCaiJ  -    (Daca^t;j;andle)GetWR<::CQ.v  (W  j  nc&wToPr  i  st  > ; 

HLerk:  [TL-LeKj6lCQrO  ; 

a-jtFLr   -  * These f Con; 

if   iauxitr  ->  Fi.iij)  ,<*  ri<irLzero  — >  font   */ 

t'or.thai-.d  I  c:  -    ( FDat  aEs  ii  i  sr.diej  GetHS.L!  r^n  n  (wi  n-do-TuP  r  i  nt : ;        /  *  ,,,,,-,■„ 
HT.r^irJtiFo^^Iliindla)  ;  ,'*    to   u.u;:;  '/ 

boiitPLi   -  *?-ontrrtndIsr  /»  the  ria-t      V 

fe^awiPmjtftt  -?  ftti.  Font  Fir);  /«  .j:.ur5  ».ji 

:-Jy  ni  ooi  1  F(!jilW,t  nd  1  e )  ; 

:■ 

else 


KraiSekfi'neHii  £"».■:)  r' 


/"   Pice  urn  Window  V 
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HP.H  (global  data) 


♦include  <types.h> 
♦include  <quickdraw.h> 
♦include  <font.h> 

♦define  SCREENMODE  0x80 

Idefine  MAXSCAN  160 

ideflne  QDAuxTool   18 

•define  PManager     19 

Idefine  MinVer  0 

♦  define  VolNotFound   0x45 


/*  640  mode  */ 

/*  Auxiliary  Quickdraw  */ 

/*  Print  Manager  Tool  Number  */ 

/*  Minimun  Version  for  them  */ 


(define 

NUM  MENUS 

5 

tdefine 

NUM_WINDOWS 

15 

/*  Menus  related  defines  */ 

Idefine 

AppleMenuID 

1 

Idefine 

FileMenuID 

2 

Idefine 

EditMenuID 

3 

Idefine 

ModeMenuID 

4 

Idefine 

Window sMenuID 

5 

♦define 

FontsMenuID 

6 

♦define 

Undo ID 

250 

Idefine 

CutID 

251 

♦define 

CopylD 

252 

♦define 

PastelD 

253 

♦define 

ClearlD 

254 

♦define 

CloseWID 

255 

♦define 

About ID 

256 

♦define 

Quit ID 

257 

♦define 

OpenWID 

258 

♦define 

SavelD 

259 

♦define 

ChooselD 

260 

♦define 

SetUpID 

261 

♦define 

PrintID 

262 

♦define 

ModelD 

263 

♦define 

ShowFontID 

264 

♦define 

Mono ID 

265 

/*  Number  of  menus  */ 

/*  Maximum  number  of  windows  */ 


/*  These  next  6  are  standard  and  */ 
/*  required  for  DA  support  under  */ 
/*  TaskMaster.  */ 


/*  These  are  our  own  responsibility  */ 


/*  some  font  and  window  handling  stuff  */ 
♦  define  MaxNameSize  29 

♦define  NumLines  13 

typedef  struct  DataRec  { 

char  **PicHand; 

char  Blank; 

char  Str[30] ; 

char  MMStuff [6] ; 

short  Flag; 

char  Extra; 

)  DataRec,  *DataRecPtr, 


**DataRecHandle; 
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/*  same  thing  as  DataRec  but  for  FONT  windows  */ 
typedef  struct  FontDataRec  ( 

lTrXBllZ  '*   ThlS  1S  PiC  handlS  ln  DataR6C  *' 

char  Str[30J ; 
char  MMStuff [6]  ; 
Byte  Flag; 
char  Extra; 

)  FDataRec,  *FDataRecPtr,  **FDataRecHandle; 
typedef  int  PackedData [320J; 

typedef  struct  DirEntry 
1 

int  PackedBytes; 
word  Mode; 
)  DirEntry; 

typedef  struct  MainBlk  { 

long  SizeOfBlock; 

char  IDStr[5]  ; 

word  MasterMode; 

int  PixelsPerScanLine; 

int  NumPallets; 

int      PalletArray[16]  [16]; 

int  NumScanLines; 

DirEntry  ScanLineDir[200] ; 

PackedData  PackedScanLines[200] ; 

)  MainBlk, *MainBlkPtr, **MainBlkHandle; 

"  D^?Hft„:t  ifs0r„hy'S  Pr09ram  inClUde  HP-H'  bUt  "0t  a11  d°  the  same  with 
*/ 

#ifndef  dialog 

typedef  struct  ItemTemplate   { 

Word  itemID;  /*  ItemTemplate  -  */ 

Rect  itemRect;  /*  ItemTemplate  -  */ 

Word  itemType;  /*  ItemTemplate  -  */ 

Pointer  itemDescr;  /*  ItemTemplate  -  */ 

Word  itemvalue;  /*  ItemTemplate  -  */ 

Word  itemFlag;  /*  ItemTemplate  -  */ 

"  "In,"  ■"""■  ""  a"l0»  ""■*""  —«  "'  «■"*«  rn.  s,,  .„„  Pu« 

*/ 

#ifndef  GetPutListLength 

♦  define  GetPutListLength  OxF   /*  Set  to  IS  um,k  ,   tk 

#endif  to  15  whlch  is  the  max  */ 

typedef  struct  GetPutTemplate  ( 
Rect     gpBoundsRect; 
Boolean     gpVisible; 
LongWord     gpRefCon; 

ItemTempPtr     gpItemList [GetPutListLength] • 
}  GetPutTemplate,   *GetPutTempPtr  ■ 
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Appendix  G 


HodgePodge    Source    Code: 
Pascal 


HP.PAS  414 
MENU. PAS  419 
EVENT.PAS  422 
WIN  DOW.  PAS   425 
DIALOG.PAS  429 
FONT. PAS  434 
PRINT.PAS  437 
PAINT.PAS  439 
GLOBALS.PAS  443 


413 
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HP.PAS  (main  program) 


program  Hodgepodge; 

{+ + 

Hodgepodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


This  program  and  its  derivatives  are  licensed  only  for 
use  on  Apple  computers. 

Works  based  on  this  program  must  contain  and 
conspicuously  display  this  notice. 

This  software  is  provided  for  your  evaluation  and  to 
assist  you  in  developing  software  for  the  Apple  IIGS 
computer. 

This  is  not  a  distribution  license.  Distribution  of 
this  and  other  Apple  software  requires  a  separate 
license.  Contact  the  Software  Licensing  Department  of 
Apple  Computer,  Inc.  for  details. 

DISCLAIMER  OF  WARRANTY 

THE  SOFTWARE  IS  PROVIDED  "AS  IS"  WITHOUT 
WARRANTY  OF  ANY  KIND,  EITHER  EXPRESS  OR  IMPLIED, 
WITH  RESPECT  TO  ITS  MERCHANTABILITY  OR  ITS  FITNESS 
FOR  ANY  PARTICULAR  PURPOSE.   THE  ENTIRE  RISK  AS  TO 
THE  QUALITY  AND  PERFORMANCE  OF  THE  SOFTWARE  IS  WITH 
YOU.   SHOULD  THE  SOFTWARE  PROVE  DEFECTIVE,  YOU  (AND 
NOT  APPLE  OR  AN  APPLE  AUTHORIZED  REPRESENTATIVE) 
ASSUME  THE  ENTIRE  COST  OF  ALL  NECESSARY  SERVICING, 
REPAIR  OR  CORRECTION. 

Apple  does  not  warrant  that  the  functions 
contained  in  the  Software  will  meet  your  requirements 
or  that  the  operation  of  the  Software  will  be 
uninterrupted  or  error  free  or  that  defects  in  the 
Software  will  be  corrected. 

SOME  STATES  DO  NOT  ALLOW  THE  EXCLUSION 
OF  IMPLIED  WARRANTIES,  SO  THE  ABOVE  EXCLUSION  MAY 
NOT  APPLY  TO  YOU.   THIS  WARRANTY  GIVES  YOU  SPECIFIC 
LEGAL  RIGHTS  AND  YOU  MAY  ALSO  HAVE  OTHER  RIGHTS 
WHICH  VARY  FROM  STATE  TO  STATE. 
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(HodgePodge  Apple  IIGS  Toolbox  Interface  Units) 


(Hodgepodge  Code  Units) 


HPIntfData, 
HPIntfProc, 
HPIntfPdos, 

Globals, 

Dialog, 

Font, 

Paint, 

Window, 

Print, 

Menu, 

Event ; 

function  StartUpTools  :  boolean; 

(Routine  to  start  up  the  Apple  IIGS  toolbox.  We  attempt  to  start  up  all 
the  managers  that  we  need,  checking  each  time  if  an  error  occurred  during 
startup.  True/false  is  returned  by  this  routine  depending  on  its  success. 
If  the  RAM-based  tools  cannot  be  loaded,  the  user  is  prompted  to  install 
a  system  disk  and  is  given  the  option  of  trying  again  or  exitting.  The 
latter  option  exits  this  procedure  with  a  False  result.  Tool  startup 
errors  result  in  a  call  to  the  system  death  handler  (the  bouncing  apple) , 
with  a  code  showing  where  we  died  as  well  as  the  actual  tool  error  number.) 


const  DPForQuickDraw 

=  $000; 

(Needs  3  pages) 

DPForEventMgr 

=  $300; 

(Needs  1) 

DPForCtlMgr 

=  $400; 

(Needs  1) 

DPForLineEdit 

=  $500; 

(Needs  1) 

DPForMenuMgr 

-  $600; 

(Needs  1) 

DPForStdFile 

-  $700; 

(Needs  1) 

DPForFontMgr 

-  $800; 

(Needs  1) 

DPForPrintMgr 

-  $900; 

(Needs  2) 

TotalDP 

-  $B00; 

(Total  direct  page  space) 

var  toolRec    :  ToolTable; 
paramBlock  :  FileRec; 
baseDP     :  integer; 

label  1;   (Just  for  once,  let's  commit  the  cardinal  sin  of  using  the  GOTO!) 

begin   (of  StartUpTools) 

StartUpTools  :=  true;  (Assume  all  is  well  at  first) 


TLStartUp; 
CheckToolError  ($1) ; 

MyMemorylD  :=  MMStartUp; 
MTStartUp; 
CheckToolError  ($2) ; 


(Init  Tool  Locator  ) 


Unit  Memory  Manager) 
(Init  Misc  Tools    ) 


(Allocate  memory  space  in  bank  0  for  direct-page  use  by  GS  Tools:) 

ToolsZeroPage  :- 

NewHandle  (TotalDP,  (Allocate  memory) 

MyMemorylD,  (Process  (user)  ID) 

attrBank+attrFixed+attrLocked+attrPage,  (Attributes) 
Ptr  (0));  (Start  in  bank  0  ) 

CheckToolError  ($3); 

baseDP  :-   LoWord  (ToolsZeroPage*) ; 


QDStartUp 

(baseDP  +  DPForQuickDraw, 

ScreenMode, 

MaxScan, 

MyMemorylD) ; 
CheckToolError  ($4); 


(Address  of  zpag  ♦  3  ) 
(640  mode  ) 

(Horizontal  line  size) 
(Process  (user)  ID   ) 
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EMStartUp 

(baseDP  +  DPForEventMgr, 

20, 

0, 

MaxX, 

0, 

200, 

MyMemorylD) ; 
CheckToolError  ($5); 

(Give  a  message  while  we  load  RAM  based  tools:) 


(Address  of  zpag  #  4 
(Event  queue  size 
(X  min  clamp 
(X  max  clamp 
(Y  min  clamp 
(Y  max  clamp 
(Process  (user)  ID 


MoveTo 
SetBackColor 
SetForeColor 
Drawstring 

ShowCursor; 


(20,20); 
(0); 

(15); 

('One  Moment  Please...1); 


(Now  load  RAM  based  tools  (and  RAM  patches 
toolRec.NumTools  :=  14; 


toolRec 

.Tools 

[1] .TSNum  :=  4; 

toolRec 

.Tools 

;i) .MinVersion  := 

0; 

toolRec 

.Tools 

.2] .TSNum  :=  5; 

toolRec 

.Tools 

;2J .MinVersion  :- 

0; 

toolRec 

Tools 

;3] .TSNum  :=  6; 

toolRec 

Tools 

.3] .MinVersion  :- 

0; 

toolRec 

.Tools 

!4] .TSNum  :=  14; 

toolRec 

Tools 

.4] .MinVersion  := 

0; 

toolRec 

Tools 

!5) .TSNum  :=  15; 

toolRec 

Tools 

\5] .MinVersion  :- 

0; 

toolRec 

Tools 

.6]  .TSNum  :=  16; 

toolRec 

Tools 

6] .MinVersion  :- 

0; 

toolRec 

Tools 

7] .TSNum  :-  18; 

toolRec 

Tools 

7] .MinVersion  := 

0; 

toolRec 

Tools 

8] .TSNum  :=  19; 

toolRec 

Tools 

8] .MinVersion  :- 

0; 

toolRec 

Tools 

9]  .TSNum  :-  20; 

toolRec 

Tools 

9) .MinVersion  := 

0; 

toolRec 

Tools 

riO] .TSNum  :=  21; 

toolRec 

Tools 

10] .MinVersion  :■ 

■  0; 

toolRec 

Tools 

11] .TSNum  :-  22; 

toolRec 

Tools 

11] .MinVersion  := 

■  0; 

toolRec 

Tools 

12] .TSNum  :-  23; 

toolRec 

Tools 

12] .MinVersion  :■ 

■  0; 

toolRec 

Tools 

13] .TSNum  :=  27; 

toolRec 

Tools 

13] .MinVersion  := 

'  0; 

toolRec 

Tools 

14] .TSNum  :=  28; 

toolRec 

Tools 

14] .MinVersion  := 

0; 

to  ROM  tools!) : ) 
(QuickDraw  II 
(Desk  Manager 
(Event  Manager 
(Window  Manager 
(Menu  Manager 
(Control  Manager 
(QuickDraw  Aux 
(Print  Manager 
(Line  Edit 
(Dialog  Manager 
(Scrap  Manager 
(Standard  File 
(Font  Manager 
(List  Manager 


paramBlock. pathname  :=  @' * /SYSTEM/TOOLS' 
GET_FILE_INFO  (paramBlock)  ; 
if  toolErr  <>  0  then 

if  MountBootDisk  -  1  then 

goto  1 
else  begin 

StartUpTools  :=  false; 
Exit; 
end; 

LoadTools      (toolRec); 
CheckToolError  (S6)  ; 

WindStartUp    (MyMemorylD)  ; 
CheckToolError  ($7); 


(Make  sure  tools  avail) 


(Load  the  tools  I  need) 
(Init  Window  Manager  ) 


Appendix  G:  HodgePodge  Source  Code:    Pascal 


RefreshDesktop  (nil); 


(Draw  the  desktop 


) 


CtlStartUp 

(MyMemorylD, 
baseDP  +  DPForCtlMgr) ; 
CheckToolError  ($8) ; 

LEStartUp 

(baseDP  +  DPForLineEdit, 
MyMemorylD) ; 
CheckToolError  ($9) ; 

Dialog  Startup 

(MyMemorylD) ; 
CheckToolError  ($A) ; 

MenuStartUp 

(MyMemorylD, 

baseDP  +  DPForMenuMgr) ; 
CheckToolError  (SB) ; 

DeskStartUp; 
CheckToolError  (SC) ; 

ShowPleaseWait; 

SFStartUp 

(MyMemorylD, 

baseDP  +  DPForStdFlle) ; 
CheckToolError  (SD) ; 
SFAllCaps  (true) ; 

QDAuxStartUp; 
CheckToolError  ($E) ; 
WaitCursor; 

FMStartUp 

(MyMemorylD, 

baseDP  +  DPForFontMgr)  ; 
CheckToolError  (SF) ; 

ListStartUp; 
CheckToolError  ($10); 

ScrapStartUp; 
CheckToolError  ($11); 

PMStartUp 

(MyMemorylD, 

baseDP  +  DPForPrlntMgr) ; 
CheckToolError  ($12); 

HidePleaseWalt; 
InltCursor; 

end;    (of  StartUpTools) 


(Inlt  Control  Manager) 
(Process  (user)  ID  ) 
(Address  of  zpag  #  5  ) 


(Inlt  Line  Edit  ) 
(Address  of  zpag  #  6  ) 
(Process  (user)  ID   ) 


(Init  Dialog  Manager  ) 
(Process  (user)  ID   ( 


(Init  Menu  Manager  ) 
(Process  (user)  ID  ( 
(Address  of  zpag  #  7  ) 


(Init  Desk  Manager   ) 

(Put  up  dialog  box   ) 

(Init  Standard  File  1 
(Process  (user)  ID  ) 
(Address  of  zpag  #  8  ( 

(I  want  filenames  in  all  caps) 

(Init  QuickDraw  Auxil) 

(Wristwatch  cursor   ) 

(Init  Font  Manager  ) 
(Process  (user)  ID  ) 
(Address  of  zpag  #  9  ) 

(Init  List  Manager   ) 

(Init  Scrap  Manager  ) 


(Init  Print  Manager  ) 
(Process  (user)  ID  ) 
(Address  of  zpag  #  10 ( 


(Remove  dialog  box   ) 
(Normal  arrow  cursor  ) 


HP. PAS  (main  program) 


procedure  ShutDownTools; 

(Routine  to  shut  down  all  the  tools  we  used  in  reverse  order  of  startup. 
Only  tools  which  are  currently  active  are  shut  down;  this  facilitates 
recovery  from  an  error  condition  from  StartUpTools. J 

begin   {of  ShutDownTools) 

DeskShutDown; 

if  WindStatus  <>  0  then 

HideAllWindows;     {Close  all  windows  only  if  OK!   Takes  some  time  1 

ListShutDown; 

FMShutDown; 

ScrapShutDown; 

PMShutDown; 

QDAuxShutDown; 

SFShutDown; 

MenuShutDown; 

DialogShutDown; 

LEShutDown; 

CtlShutDown; 

WindShutDown; 

EMShutDown; 

QDShutDown; 

MTShutDown; 

if  MMStatus  <>  0  then  begin 

DisposeHandle  (ToolsZeroPage) ;   {Deallocate  tool  directpage  space) 
MMShutDown     (MyMemorylD)  ;     {Do  this  only  if  OK!) 

end; 

TLShutDown; 

end;    {of  ShutDownTools) 


BEGIN   (of  MAIN  program  Hodgepodge) 

InitGlobals;  {  mitialze  our  globals,  menus,  etc.  ) 

if  StartUpTools  then  begin      {  Initialize  IIGS  Tools  ) 
SetUpDefault;  (  Set  up  print  dialog  ) 

SetUpMenus;  (  set  up  menus  ) 

SetUpWindows;  {  set  up  windows  ) 

MainEvent;  (  Use  application  ) 

end; 

ShutDownTools;  {  Shut  down  IIGS  Tools  ) 

END.    {of  MAIN  program  Hodgepodge) 
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MENU.PAS  (menus) 


UNIT  Menu; 


Hodgepodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Pascal  UNIT  "MENU.PAS"  :  Menu  bar  setup  and  menu  item  handling 


+ 


+} 


INTERFACE 


HPIntfData, 
HPIntfProc, 
HPIntfPdos, 

Globals, 

Dialog, 

Font, 

Paint, 

Window, 

Print; 


(HodgePodge  Apple  IIGS  Toolbox  Interface  Units) 


{Hodgepodge  Code  Units} 


procedure  DoMenu;      {Execute  a  menu  item} 

procedure  SetUpMenus;   {Install  menus  and  redraw  menu  bar} 


IMPLEMENTATION 

procedure  AddToMenu; 

{Private  routine  to  add  a  new  window  item  to  the  "Windows"  menu  after  a 
new  window  has  been  drawn.  Increments  the  variable  WIndex,  a  count  of 
the  number  of  windows  currently  open. } 

var  theWindow    :  GrafPortPtr; 
myDataHandle  :  WindDataH; 

begin   {of  AddToMenu} 

theWindow  :=  FrontWindow; 

WindowList  [WIndex]  :-  theWindow; 

myDataHandle  :-  WindDataH  (GetWRefCon  (theWindow)); 

InsertMItem  (UmyDataHandleA* .menuStr  [1] , $FFFF,WindowsMenuID) ; 
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if  WIndex  =  0  then  begin  (This  is  the  first  window) 

DeleteMItem  (NoWindowsItem) ;        (Remove  the  "filler"  item) 
SetMenuFlag  ($FF7F,WindowsMenuID) ;   (Highlight  the  menu) 
DrawMenuBar; 
end; 

CalcMenuSize  (0,  0,WindowsMenuID) ; 
Inc  (WIndex) ; 
end;     (of  AddToMenu) 
procedure  DoOpenltem; 

(Private  routine  which  is  called  when  the  "Open..."  item  from  the  "File" 
menu  OR  the  "Display  Font..."  item  from  the  "Fonts"  menu  is  selected 
(OpenWindow  will  determine  which  one  it  was) .   If  too  many  windows  are 
already  open,  then  a  dialog  is  displayed.) 

begin   (of  DoOpenltem) 

if  WIndex  <  LastWind  then 
if  OpenWindow  then 

AddtoMenu 
else 
else 

ManyWindDialog; 
end;     (of  DoOpenltem) 


procedure  DoQuitltem; 

(Private  routine  to  set  Done  flag  if  the  "Quit"  item  was  selected) 

begin    (of  DoQuitltem) 

Done  :=  true; 
end;    (of  DoQuitltem) 


procedure  DoWindow  (itemNum:  integer); 

(Private  routine  which  brings  a  specific  window  to  the  front  of  the 
desktop,  in  response  to  a  selection  from  the  "Windows"  menu. ) 

var  theWindow:  GrafPortPtr; 

begin   (of  DoWindow) 

theWindow  :=  WindowList  [itemNum  -  Firstwindltem] ; 

SelectWindow  (theWindow) ; 

ShowWindow   (theWindow) ; 
end;     (of  DoWindow) 
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procedure  DoMenu; 

(Procedure  to  handle  all  menu  selections.  Examines  the  Event. TaskData 
menu  Item  ID  word  from  TaskMaster  (from  Event  Manager)  and  calls  the 
appropriate  routine.  While  the  routine  is  running  the  menu  title  is 
still  highlighted.   After  the  routine  returns,  we  unhilight  the 
menu  title. ) 


var  menuNum 

itemNum 


integer; 
integer; 


begin   (of  DoMenu) 

menuNum  :=  HiWord  (Event. wmTaskData) ; 
itemNum  :-  LoWord  (Event .wmTaskData) ; 


case  itemNum  of 

Aboutltem 

Ope nit em 

Closeltem 

SaveAsItem 

ChoosePItem 

PageSetltem 

Prlntltem 

Quit It em 

Undoltem 

Cutltem 

Copyltem 

Pasteltem 

Clearltem 

Font Item 

Monoltem 
otherwise 

DoWindow  (itemNum) ; 
end; 


DoAboutltem; 

DoOpenltem; 

DoCloseltem; 

DoSaveltem; 

DoChooserltem; 

DoSetupItem; 

DoPrintltem; 

DoQultltem; 


DoOpenltem; 
DoSetMono; 


HiliteMenu  (false, menuNum) ; 
end;    (of  DoMenu) 


(Unhighlight  the  menu  title) 


procedure  SetUpMenus; 

(Procedure  to  install  our  menu  titles  and  their  items  in  the  system  menu 
bar  and  to  redraw  it  so  we  can  see  them. ) 

var  height  :  integer; 


begin   (of  SetUpMenus) 
SetMTitleStart  (10) ; 


(Set  Starting  position  of  menu) 


InsertMenu  (NewMenu  (@FontMenuStr  [1]),0) 

InsertMenu  (NewMenu  (gWindowMenuStr  [1]),0) 

InsertMenu  (NewMenu  OEditMenuStr  [1]),0) 

InsertMenu  (NewMenu  (@FileMenuStr  (1]),0) 

InsertMenu  (NewMenu  (SAppleMenuStr  [1]),0) 


(Fonts  Menu 
(Window  Menu 
(Edit  Menu 
(File  Menu 
(Apple  Menu 


FlxAppleMenu  (AppleMenuID)  ; 
height  :-  FixMenuBar; 
DrawMenuBar; 
end;    (of  SetUpMenus) 


(Add  DAs  to  apple  menu  ) 
(Set  sizes  of  menus  ) 
{...and  draw  the  menu  bar!) 
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EVENT.PAS  (main  event  loop) 

UNIT  Event; 

{+ + 

Hodgepodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 

Pascal  UNIT  "EVENT.PAS"  :  Event  loop  and  dispatching  routine 

+  ) 

INTERFACE 

USES 

HPIntfData,         (Hodgepodge  Apple  IIGS  Toolbox  Interface  Units) 

HPIntfProc, 

HPIntfPdos, 

Globals,  (Hodgepodge  Code  Units) 

Dialog, 

Font, 

Paint, 

Window, 

Print, 

Menu; 


procedure  MainEvent;    (Main  event  handling  loop  which  repeats  until  Quit) 


IMPLEMENTATION 


procedure  MainEvent; 

{Main  event  handling  routine  which  loops  until  the  Done  flag  is  set  by 

selection  of  the  "Quit"  item.   We  call  the  Window  Manager's  TaskMaster 
routine,  which  calls  the  Event  Manager's  GetNextEvent  routine  and 
handles  window  resize  tracking/resizing,  window  movement  tracking/resizing 
window  activiation  (bringing  to  front  by  clicking  on  an  inactive  window) , 
among  other  things.  TaskMaster  returns  control  to  us  when  the  user  has 
clicked  a  window's  GoAway  check  box,  or  when  the  user  has  selected  a  menu 
item,  either  with  the  mouse  or  with  an  equivalent  Solid-Apple  keystroke 
sequence. ) 

var  code  :  integer; 
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procedure  CheckFrontW; 

(Check  to  whom  the  front  window  belongs  to  (us  or  a  Desk  Accessory  (DA)), 
and  if  it  belongs  to  us,  whether  it  is  appropriate  to  disable  (dim)  certain 
menu  items  (such  as  the  Save  item)  or  to  enable  them.  Private  routine.) 

var  theWindow    :  GrafPortPtr; 
myDataHandle  :  WindDataH; 


procedure  Disableltems; 

(Private  routine  to  disable  (dim)  certain  menu  titles) 

begin   (of  Disableltems) 

DisableMItem  (SaveAsItem) ; 

DisableMItem  (Closeltem) ; 

DisableMItem  (Printltem)  ; 

DisableMItem  (PageSetltem); 
end;     (of  Disableltems) 


procedure  Enableltems; 

(Private  routine  to  enable  (undim)  certain  menu  titles) 

begin    (of  Enableltems) 

EnableMItem  (SaveAsItem); 

EnableMItem  (Closeltem) ; 

EnableMItem  (Printltem) ; 

EnableMItem  (PageSetltem) ; 
end;     (of  Enableltems) 


procedure  DisableAll; 

(Private  routine  to  disable  all  menu  titles  for  Desk  Accessory  (DA) ) 

begin   (of  DisableAll) 

SetMenuFlag  ($0080, EditMenuID) ; 

DrawMenuBar; 

Disableltems; 
end;     (of  DisableAll) 
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procedure  SetUpForAppW; 

1privaeteiroutinTjiCati0n  "^    (°UrS>    ls  the  fr°"t  »!»*». 


begin    {of  SetUpForAppW) 

SetMenuFlag  (50080, EditMenuID) ■ 

DrawMenuBar; 

Enableltems; 
end;     {of  SetUpForAppW) 


procedure  SetUpForDAW; 

(Called  If  a  Desk  Accessory's  window  Is  the  frontmost  window.  Private.) 
begin    (of  SetUpForDAW) 

Disableltems; 

EnableMItem  (Closeltem) ; 

SetMenuFlag  ($FF7F, EditMenuID) ; 

DrawMenuBar; 
end;     {of  SetUpForDAW) 


begin    {of  CheckFrontW) 

theWindow  :=  FrontWlndow; 

if  theWindow  =  lastwindow  then 
Exit; 

if  theWindow  -  nil  then 

DlsableAll 
else  begin 

if  GetSysWFlag  (theWindow)  =  true  then 
SetUpforDAW 
else  begin 

SetUpforAppW; 

DisableMItem  (SaveAsItem) 
end; 

end; 

lastWindow  :=.  theWindow 
end;     {of  CheckFrontW) 


begin   (of  MainEvent) 

Event. wmTaskMask  :-  SOOOOIfff-   /m 

Don*  =  false        A1l°w  TaskMaster  to  do  everything) 

'      {D°ne  fla9  wil1  be  set  by  Quit  item) 
repeat 

CheckFrontW; 

code  :=  TaskMaster  (SFFFF, Event) • 

case  code  of  ' 

wlnGoAway   :  DoCloseltem; 
wlnSpecial, 

wlnMenuBar   :  DoMenu- 
end; 
until  Done; 
end;     {of  MainEvent) 


END. 
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WINDOW.PAS  (windows) 


UNIT  Window; 


HodgePodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  198  6-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Pascal  UNIT  "WINDOW.PAS"  :  Routines  to  open  and  close  windows 


-+1 


INTERFACE 


HPIntfData, 
HPIntfProc, 
HPIntfPdos, 

Globals, 
Dialog, 
Paint, 
Font; 


(HodgePodge  Apple  IIGS  Toolbox  Interface  Units) 


(HodgePodge  Code  Units) 


procedure  DoCloseltem; 
procedure  HideAllWindows; 
function  OpenWindow  :  boolean; 
procedure  SetUpWindows; 


(Closes  current  frontmost  window  ) 

(Closes  all  windows  on  the  desktop  ) 
(Tries  to  open  a  font  or  picture  window  ) 
(Initialize  variables  for  stacking  windows) 


IMPLEMENTATION 


myWind 
wXoffset 
wYoffset 
iSizPos 


ParamList; 
integer; 
integer- 
Re  ct; 


procedure  DoCloseltem; 

(This  procedure  closes  the  frontmost  window  and  deallocates  all  of  its 
associated  storage.   NDA  windows  are  supported  for  when  this  procedure 
is  called  by  HideAllWindows  when  exitting  HodgePodge.) 

var  theWindow    :  GrafPortPtr; 
myDataHandle  :  WindDataH; 
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procedure  AdjWind  (theWindow:  Graf Port Pt r ) ; 

(Finds  the  window  designated  by  theWindow  and  removes  it  from  the 
WindowList  and  returns  the  position  in  the  window  list  where  it  was 
found.  Private  function.) 

var  i      :  integer; 
theOne  :  integer; 

begin   {of  AdjWind) 

{Find  the  index  of  the  grafportptr  of  the  window  being  deleted-) 

i  :-  firstWind; 

while  WindowList  [i]  <>  theWindow  do 

Inc  (i); 
theOne   :=  i; 

{Remove  corresponding  item  from  the  WINDOW-menu: ) 

if  WIndex  =  1  then  begin  (LaSt  window-special  case) 

InsertMItem  (ONoWindStr  [1]  ,FirstWindItem  +  theOne,WindowsMenuID)  ; 

SetMenuFlag  ($0080,WindowsMenuID) ; 

DrawMenuBar; 

wXoffset  :=  20; 

wYoffset  :=  12; 
end; 

DeleteMItem    (FirstWindltem  +  theOne); 
CalcMenuSize   (0, 0,WindowsMenuID) ; 

{Physically  delete    (scroll)    the  grafportptr  of  the   ill-fated  window:) 
Inc    (i) ;  ' 

while  i  <  LastWlnd  do  begin 

WindowList  [i  -  1]  :-  WindowList  [il; 

Inc  (i); 
end; 

{Renumber  the  WINDOW-menu  items:) 
for  i  :=  theOne  to  Lastwind  do 

SetMItemlD  (FirstWindltem+i-l  {new  ID)   ,   FirstWindltem+i  {old  ID)), 
end;     {of  AdjWind) 

begin    (of  DoCloseltem) 

theWindow  :=  FrontWindow; 
CloseNDAbyWinPtr  (theWindow) ; 

"  'Sl'r  thS"  ^9'n  fIt  wasn,t  a"  N»  window) 

ttntt     h,    (theWlnd°")'-  (Update  WINDOW  menu) 

myDataHandle   :-  WindDataH  (GetWRefCon  (theWindow)); 
DisposeHandle  (Handle  (myDataHandle));   (Deallocate  storage) 

CloseWindow    (theWindow);  {Remove  the  window) 

end-              (WIndex);  (Index  into  window  list) 
end;     (of  DoCloseltem) 
procedure  HideAllWindows; 

{Repeatedly  call  DoCloseltem  to  close  the  frontmost  window  (which  has  the 
effect  of  making  the  next  deeper  level  window  the  frontmost  one)  until 
there  is  no  frontmost  window  anymore;  ie,  there  are  no  more  windows.) 

begin    {of  HideAllWindows) 

while  FrontWindow  <>  nil  do 
DoCloseltem; 
end;     {of  HideAllWindows) 
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function  OpenWindow  :  boolean; 

(Tries  to  open  either  a  font  or  picture  window,  depending  on  the 
Event. TaskData  returned  from  TaskMaster  (which  got  it  from  the 
Event  Manager) .  True/false  is  returned  depending  on  whether  a 
window  was  actually  opened.  Note  the  way  in  which  the  different 
functions  are  called  in  the  if-then-else  structure  below.   Each 
function  tries  to  do  what  its  name  implies,  and  the  true/false 
result  that  each  returns  is  used  to  determine  if  the  next  logical 
function  should  be  called.) 


function  DoTheOpen:  boolean; 

(This  function  tries  to  open  a  window  and  returns  true/false  depending  on 
its  success. } 

var  theWindow    :  GrafPortPtr; 

myDataHandle  :  WindDataH; 

theMenuStr   :  Str255; 

ourFontlnfo   :  FontlnfoRecord; 

begin   (of  DoTheOpen) 
DoTheOpen  :-  false; 

myDataHandle  :=  WindDataH  (NewHandle  (sizeof  (WindDataRec) , 

MyMemorylD, 

attrLocked  +  attrFixed, 
Ptr  (0))); 

if  isToolError  then 
Exit; 


with  myWind  do  begin 


paramLength 

- 

sizeof  (ParamList); 

wFrameBits 

- 

$DDA0; 

wRefCon 

= 

longint  (myDataHandle) ; 

SetRect 

(wZoom,  0,26,  620, 190)  ; 

wColor 

- 

nil; 

wYOrigin 

= 

0; 

wXOrigin 

= 

0; 

wDataH 

= 

188; 

wDataW 

- 

640; 

wMaxH 

= 

200; 

wMaxW 

= 

640; 

wScrollVer 

= 

4; 

wScrollHor 

= 

16; 

wPageVer 

= 

4  0; 

wPageHor 

= 

160; 

wlnfoRefCon 

= 

0; 

wlnfoHeight 

= 

0; 

wFrameDefProc 

- 

nil; 

wlnfoDefProc 

= 

nil; 

wPlane 

= 

-l; 

wStorage 

= 

nil; 

end; 

theMenuStr  :»  cone 

:a 

:  ('=-', 

myReply . filename, 

■\N', 

IntToString  (FirstWindltem  +  WIndex) , 

•\0.'); 

with  myDataHandle**  do  begin 


Name 

MenuStr 

MenuID 


end; 


=  myReply. filename; 

=  theMenuStr; 

=  FirstWindltem  +  WIndex; 
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if  LoWord  (Event. wmTaskData)  -  Fontltem  then  begin 
(We're  opening  a  font  window:} 
myWind.wContDefProc  :=  @DispFontWindow; 
with  myDataHandle""  do  begin 


flag 
theFont 
isMono 
end; 

InstallFont 
GetFontlnfo 


1; 

DesiredFont; 

isMonoFont; 


(DesiredFont, 0) ; 
(ourFontlnfo) ; 
MyWind.wDataH  :-  15  (NumLines+2)  * 

(OurFontlnfo. ascent  +  ourFontlnfo. descent) ; 
(Call  to  a  FindMaxWidth  procedure  would  be  placed  here  to  set 
the  MyWind.wDataW  field  to  length  of  the  longest  line  of  text.) 
end  else  begin 

(We're  opening  a  picture  window:} 
myWind.wContDefProc  :-  @Paint; 
with  myDataHandle*A  do  begin 
flag  :-  0; 
pict  :=  PictHndl; 
end; 
end; 


with  myWind  do  begin 

wTitle    :-   @myDataHandle'w\Nanie; 


SetRect    (wPosition, wXoffset  +  iSizPos.hl, 

wYoffset  +  ISizPos.vl, 

wXoffset  +  iSizPos.h2, 

wYoffset  +  iSizPos.v2); 


end; 


wXoffset  :=  wXoffset  +  20;   (Update  globals  which  offset  new  window  pos) 
wYoffset  :=  wYoffset  +  12; 

if  wYoffset  >  120  then      (Cause  stacking  effect) 
wYoffset  :=  12; 


(Now  create  the  window:) 
theWindow  :-  NewWindow 
SetPort 
SetOriginMask 

InitCursor; 
DoTheOpen  :-  true; 
end;     (of  DoTheOpen) 


(myWind)  ; 
(theWindow) ; 
($FFFE, theWindow) ; 

(Go  back  to  the  arrow  cursor) 
(Indicate  successful  completion) 


begin    (of  OpenWindow) 
OpenWindow  :=  false; 

if  LoWord  (Event .wmTaskData)  =  Fontltem  then  begin 
if  DoChooseFont  then 
if  DoTheOpen  then 

OpenWindow  :=  true 
end  else  begin 

if  AskUser  then 

if  DoTheOpen  then 

OpenWindow  :-  true 
end; 
end;     (of  OpenWindow) 

procedure  SetUpWindows; 


begin   (of  SetUpWindows) 

wXoffset  :=  20; 

wYoffset  :=  12; 

SetRect   (iSizPos,10,20,350,80); 
end;     (of  SetUpWindows) 


(Initial  window  position  offset  used  for) 
(...stacking  the  windows.) 
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DIALOG.PAS  (dialog  boxes) 


WIT  Dialog; 

+ 

Hodgepodge:  An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Pascal  UNIT  "DIALOG. PAS"  :  Dialog  and  Alert  box  drawing  routines 
^ +) 


INTERFACE 


;ses 


HPIntfData, 
HPIntfProc, 
HPIntfPdos, 


(Hodgepodge  Apple  IIGS  Toolbox  Interface  Units) 


Globals; 


(Hodgepodge  Code  Unit) 


currentlteml 
current Item2 
origPort 
msgWindPtr 


ItemTemplate; 
ItemTemplate; 
GrafPortPtr; 
GrafPortPtr; 


jrocedure  DoAboutltem; 

>rocedure  ShowPleaseWait; 

)rocedure  HidePleaseWait; 

function  CheckDlskError  (Where  :  integer) 

>rocedure  CheckToolError  (Where  :  integer) ; 

function  MountBootDisk  :  integer; 

jrocedure  ManyWindDialog; 


(About  item  in  apple  menu 
(Please  Wait  during  init 
(Erase  the  above 
boolean;  (Alert  if  ProDOS  error 
(Death  if  tool  error 
(Ask  boot  disk;  1  if  OK 
(Waits  until  OK  clicked 


DIALOG.  PAS  (dialog  boxes) 
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IMPLEMENTATION 

procedure  MakeATemplate  (TheTemplate  :  AlertTempPtr;  TheStr  :  StringPtr) ; 

(Private  routine  which  creates  an  alert  template.) 

begin    (of  MakeATemplate) 

with  TheTemplate*  do  begin 

SetRect  (atBoundsRect, 120,30,  520,  80) ; 

atAlertID  :=  1500; 

atstagel  :=  $80; 

atstage2  :=  $80; 

atstage3  :=  $80; 

atStage4   :=  $80; 

atlteml   :=  @ current It eml; 

atltem2   :=  @currentltem2; 

atltem3   :=  nil; 
end; 
with  currentlteml  do  begin 

Itemld    :-  1; 

SetRect    (ItemRect,320,25,0,0); 

ItemType   :=  10;  (Buttton  item  constant  >!<) 

ItemDescr  :=  @'OK'; 

ItemValue  :=  0; 

ItemFlag  :=  0; 

ItemColor  :=  nil; 
end; 
with  currentltem2  do  begin 

Itemld    :-  2; 

SetRect    (ItemRect,72,ll, 639,199); 

ItemType   :=  15  +  $8000;  (Disabled  Static  Text  item  constant  >'<) 

ItemDescr  :=  Pointer  (TheStr); 

ItemValue  :=  0; 

ItemFlag   :=  0; 

ItemColor  :-  nil; 
end; 
end;     (of  MakeATemplate) 

procedure  ShowPleaseWait; 

(Displays  "Please  Wait..."  dialog  box  on  the  screen.) 
var  r  :  rect; 

begin    (of  ShowPleaseWait) 

origPort   :=  GetPort; 

msgWindPtr  :-  GetNewModalDialog  (GPlsWtTemp) • 

SetRect  (r,  70, 19, 640, 200); 

NewDItem  (msgWindPtr, 1502, r, 15, @ -Please  wait  while  we  set  things  up  • 
0,0,Pointer(0)>;  y  v     ' 

Be g i nUpdat e  (msgWindPtr); 

DrawDialog   (msgWindPtr) ; 

EndUpdate   (msgWindPtr); 
end;    (of  ShowPleaseWait) 

procedure  HidePleaseWait; 

(Removes  "Please  Wait..."  dialog  box  from  the  screen.) 

begin   (of  HidePleaseWait) 

CloseDialog  (msgWindPtr) ; 

SetPort  (origPort)  ; 
end;    (of  HidePleaseWait) 
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function  CheckDiskError  (Where  :  integer)  :  boolean; 

(This  routine  checks  if  the  last  ProDOS  operation  caused  an  error.   If  so, 
then  we  change  the  cursor  to  the  arrow  cursor,  put  up  a  stop  alert 
dialog  box  with  the  text  of  the  error  message,  change  the  cursor  back  to 
the  wristwatch,  and  return  TRUE  as  the  function  result.   If  there  was  no 
disk  error,  then  we  simply  return  with  FALSE.) 


var  itemClicked 
ourAlert 
ourErrStr 
ourWhereStr 
ourString 
diskErrNum 


integer; 

AlertTemplate; 

str255; 

str255; 

str255; 

integer; 


begin    (of  CheckDiskError) 


diskErrNum 
CheckDiskError 
ourErrStr 
ourWhereStr 


=  toolErr;     (Use  the  std  C 
=  (diskErrNum  <>  0) ; 
=  'XXXX'; 
=  'XX' ; 
if  diskErrNum  <>  0  then  begin 

(***  If  desired,  get  disk  err  string  here) 
Int2Hex  (diskErrNum, 

StringPtr  (longint  (BourErrStr)  + 
4); 
Int2Hex  (Where, 

StringPtr  (longint  (gourWhereStr) 
2); 
ourString  :-  concat  ('Disk  Error  $", 
ourErrStr, 
'  occurred  at  $', 
ourWhereStr, 

' . '  > ; 

MakeATemplate  (@ourAlert, SourString) ; 
InitCursor; 

itemClicked  :=  StopAlert  (@ourAlert,  nil) ; 
(Do  not  restore  watch  cursor   ) 
end; 


like  toolerr  var  for  P/16) 
(Assign  function  result) 
(Set  string  length  byte) 
(Set  string  length  byte) 


1), 
(Get  ASCII  error  #  str  ) 

+  1), 
(Get  ASCII  where  #  str  ) 
(Build  our  error  mesg   } 


(Build  our  alert  tmplt  ) 
(Set  arrow  cursor  ) 
(Draw  dialog  &   wait    ) 


end; 


(of  CheckDiskError) 


procedure  ManyWindDialog; 

(Displays  alert  dialog  (triangle  with  "!")  with  a  message  about  no  more 
windows  being  allowed  open.   Handles  mouse  events  until  the  OK  button 
is  clicked.   Then  the  dialog  box  is  removed  and  we  return.) 

var  ourAlert    :  AlertTemplate; 
ourString   :  str255; 
itemClicked  :  integer; 

begin   (of  ManyWindDialog) 

ourString     :=  'No  more  windows,  please.'; 

MakeATemplate  (@ourAlert, @ourString) ; 

itemClicked    :=  CautionAlert  (@ourAlert,nil) ; 
end;    (of  ManyWindDialog) 


DIALOG.  PAS  (dialog  boxes) 
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procedure  CheckToolError  (Where  :  integer) ; 

(This  routine  checks  if  the  last  tool  called  returned  an  error  code. 
If  not,  then  we  just  return.  Else,  we  exit  to  the  system  death 
handler  routine  which  prints  our  string  showing  where  we  bombed.   The 
death  manager  adds  the  tool  error  code  to  the  end  of  the  string,  and 
puts  the  bouncing  apple  on  the  screen.) 

var     toolErrorSave    :    integer; 
deathMsg       :   string; 

begin   (of  CheckToolError) 

toolErrorSave  :-  ToolErrorNum; 

deathMsg      :-  '  At  $XXXX;  Could  not  handle  error  $'; 

if  toolErrorSave  <>  0  then  begin 

(Add  the  hex-in-ascii  number  to  the  string:) 
Int2Hex  (Where, StringPtr  (longint  (SdeathMsg) +6) , 4) ; 

(Halt  with  our  death  message  string  and  tool  error  code:) 
SysFallMgr  (toolErrorSave, deathMsg) ; 
end; 
end;     (of  CheckToolError) 


function  MountBootDisk  :  integer; 
var 


promptStr 

okStr 

cancelStr 

volStr 

gbvParams 


string; 
string; 
string; 
string; 
PathNameRec; 


begin    (of  MountBootDisk) 


promptStr 
okStr 

cancelStr 


-  'Please  insert  the  disk' 
=  'OK'; 

-  ' Shut  Down ' ; 


gbvParams. pathname  :-  @volStr; 

GET_BOOT_VOL  (gbvParams) ; 

MountBootDisk    :=  TIMountVolume    (174, 30, promptStr, volStr,okStr, cancelStr) ; 
end;  (of  MountBootDisk) 


procedure  DoAboutltem; 

var  aboutDlog  :  GrafPortPtr; 

r         :  Rect; 

itemHit    :  integer; 

applelconP  :  Ptr; 

applelconH  :  Handle; 

begin   (of  DoAboutltem) 

(Draw  the  dialog  box  on  the  screen:) 

SetRect  (r, 146, 20,  495, 192); 

aboutDlog  :=  NewModalDialog  (r,true, 0); 

(Add  an  OK  button  to  it:) 

SetRect  (r, 270, 153, 0,0) ; 

NewDItem  (aboutDlog, 1, r, Butt onltem, @ 'OK' , 0,  0, nil) , 

(Add  the  Apple  logo  to  it : ) 
SetRect     (r,  20, 135,  0,0); 
applelconP  :-  SApplelcon; 
applelconH  :=  SapplelconP; 
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NewDItera  (aboutDlog,3,r,IconItem  +  ItemDisable.applelconH, 0,0, nil) ; 

{Simply  write  the  text  rather  than  create  a  bunch  of  dialog  items:) 

SetPort  (aboutDlog) ; 

SetForeColor  (0)  ; 

SetBAckColor  (15); 

MoveTo  (40,17); 

SetTextFace  (8) ; 

Drawstring  ('                Hodgepodge • ) ; 

SetTextFace  (0) ; 

MoveTo  (40,27); 

Drawstring  ('       A  potpourri  of  routines  that'); 

MoveTo  (40,37); 

Drawstring  ('       demonstrate  many  features  of); 

MoveTo  (40,47); 

Drawstring  C            the  Apple  IIGS  Tools.'); 

MoveTo  (40,67); 

Drawstring  ('     By  the  Apple  IIGS  Development  Team'); 

MoveTo  (36,77); 

Drawstring  ('Translated  to  TML  Pascal  by  TML  Systems'); 

MoveTo  (40,87); 

Drawstring  ('      Copyright  Apple  Computer,  Inc. •); 

MoveTo  (40,117); 

Drawstring  ('       1986-87,  All  rights  reserved'); 

MoveTo  (40,127); 

Drawstring  ('             v4.0    23-Sep-87'); 

(Let  Dialog  Manager  handle  all  events  until  the  OK  button  is  clicked:) 
itemHit  :=  ModalDialog  (nil) ; 

{Remove  the  dialog  box  from  the  screen:) 
CloseDialog  (aboutDlog) ; 
end;     (of  DoAboutltem) 


DIALOG. PAS  (dialog  boxes) 


433 


FONT.PAS  (fonts) 


UNIT  Font; 
(+ 


Hodgepodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright    (c)    1986-87  by  Apple  Computer,    Inc. 
All   Rights  Reserved 


Pascal   UNIT   "FONT.PAS"    :    Font  window  drawing  routir 


+) 


INTERFACE 


HPIntfData,         {HodgePodge  Apple  IIGS  Toolbox  Interface  Units) 

HPIntfProc, 

HPIntfPdos, 

Globals;  {HodgePodge  Code  Unit) 


procedure  DispFontWindow;  (Draw  font  window  contents        , 

function  DoChooseFont:  boolean;  (Dialog  for  asking  font  size,  etc.) 

procedure  DoSetMono;  fSets  fl   and  af?ects  menu  ' 

procedure  ShowFont  (theFontID:  FontID;  isMono:  boolean);   {Actually  draw  font) 


IMPLEMENTATION 

procedure  DispFontWindow; 

(This  is  a  Definition  Procedure  used  to  draw  the  contents  of  a  Font 
window. ) 

var  tmpPort      :  GrafPortPtr; 
myDataHandle  :  WlndDataH; 

begin    (of  DispFontWindow) 

tmpPort      :=  GetPort; 

myDataHandle  :-  WlndDataH  (GetWRefCon  (tmpPort)); 

with  myDataHandleAA  do 

ShowFont  (theFont,isMono); 
end;     (of  DispFontWindow) 
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function  DoChooseFont :  boolean; 

(Display  the  Font  Manager's  dialog  for  the  user  to  select  a  Font, 
font  size,  and  font  style. 

The  function  returns  true  if  a  font  was  chosen,  else  false  if  the  Cancel 
button  is  pressed  in  the  dialog.   If  a  font  is  chosen,  its  FontID  information 
Is  returned  in  the  global  variable  DesiredFont.   In  addition,  the 
global  myReply. filename  contains  a  string  which  is  the  font's  file  name. 

Because  the  call  to  ChooseFont  actually  changes  the  font  of  the  current 
port,  we  must  first  save  the  current  port  and  open  a  dummy  one  do  that 
our  current  port  is  not  affected.) 


var  theFont 
dummy 
tmpPort 
tmpPortRec 
famName 


FontID; 
integer; 
GrafPortPtr; 
Graf Port; 

Str255; 


begin   (of  DoChooseFont) 
tmpPort  :=  GetPort; 
OpenPort  (StmpPortRec) ;  (Save  current  port  and  open  new  one) 

theFont  :-  ChooseFont  (DesiredFont, 0) ;   (Do  standard  dialog  box) 

if  longint  (theFont)  -  0  then       (Cancel  was  chosen) 

DoChooseFont  :=  false 
else  begin 

DesiredFont  :»  theFont;        (Update  global  DesiredFont) 

dummy  :-  GetFamlnfo  (DesiredFont . famNum, famName) ; 

myReply. filename  := 
concat  (famName, 

IntToString  (DesiredFont . fontsize) ) ; 
DoChooseFont  :=  true; 
end; 

ClosePort  (StmpPortRec) ; 

SetPort  (tmpPort);  (Restore  current  port) 

end;    (of  DoChooseFont) 


procedure  DoSetMono; 

(This  procedure  flips  the  flag  indicating  whether  we  are  currently 
displaying  a  font  in  mono-spacing  or  not,  and  updates  the 
font  menu  item  accordingly.) 

begin   (of  DoSetMono) 
if  isMonoFont  then 

SetMItem    (MonoStr,MonoItem) 
else 

SetMItem  (ProStr, Mono Item) ; 
isMonoFont  :=  not  isMonoFont; 
end;     (of  DoSetMono) 
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procedure  ShowFont  (theFontID:  FontID;  isMono:  boolean); 

var  fontlnfo  :  FontlnfoRecord; 

currHeight  :  integer; 

i,  j  :  integer; 

theCh  :  integer; 

currPt  :  Point; 

fontStr  :  Str255; 

begin   {of  ShowFont} 

InstallFont  (theFontID, 0) ; 

GetFontlnfo  (fontlnfo); 

currHeight  :=  fontlnfo. ascent  +  fontlnfo. descent  +  fontlnfo. leading; 

i  :=  GetFaralnfo  (theFontID. famNum, fontStr) ; 

fontStr  :=  concat  (fontStr,1  ',  IntToString  (theFontID. f ontSize) ) ; 

i  :=  GetFontFlags; 
if  isMono  then 

i  :-  BitOr   (i,$0001)  (Set  bottom  bit) 

else 

i  :=  Bit And  (i,S0000);         (Clear  bottom  bit) 
SetFontFlags  (i) ; 

MoveTo     (5, currHeight) ; 
Drawstring  (fontStr) ; 

MoveTo  (5, currHeight  *  3); 

Drawstring  ('The  quick  brown  fox  jumps  over  the  lazy  dog.'); 

MoveTo  (5, currHeight  *  4); 

Drawstring  ('She  sells  sea  shells  down  by  the  sea  shore.'); 

MoveTo     (5, currHeight  *  5); 

for  i  :«  0  to  7  do  begin 
Get Pen  (currPt) ; 

MoveTo  (5, currPt. v  +  currHeight) ; 
theCh  :-  i  *  32; 
for  j  :=  1  to  32  do  begin 

fontStr  [jj  :-  chr  (theCh) ; 
inc  (theCh) ; 
end; 

fontStr  [0]  :-  chr  (32); 
Drawstring  (fontStr)  ; 
end; 
end;    (of  ShowFont) 


END. 


436  Appendix  G:  HodgePodge  Source  Code:    Pascal 


PRINT.PAS  (printing) 


UNIT  Print; 


)+ 


Hodgepodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Pascal  UNIT  "PRINT.PAS"  :  Window  content  printing  routines 


-+] 


HPIntfData, 
HPIntfProc, 
HPIntfPdos, 


(Hodgepodge  Apple  IIGS  Toolbox  Interface  Units) 


Globals, 
Dialog, 
Font, 
Paint; 


(Hodgepodge  Code  Units) 


procedure  DoChooserltem; 

procedure  DoSetupItem; 

procedure  DoPrintltem; 

procedure  SetUpDefault; 


(Show  standard  chooser  dialog  to  select  options) 
(Show  standard  page  setup  dialog  to  sel  options) 
(Print  contents  of  current  window  to  printer  ) 
(Create  and  initialize  THPrint  record  ) 


IMPLEMENTATION 


var  printHndl: 


PrRecHndl;   (Private  print  record  handle  for  Print  Manager) 


procedure  DoChooserltem; 

(Display  the  Chooser  Dialog  for  the  user  to  select  which  printer  and 
printer  connection  to  use.) 

var  dummy:  boolean; 

begin   (of  DoChooserltem) 

dummy  :=  PrChooser; 
end;    (of  DoChooserltem) 
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437 


procedure  DoPrintlte 


(Print  the  contents  of  the  front  window  to  the  selected  printer.) 


var  prPort     :  GrafPortPtr; 
theWindow  :  GrafPortPtr; 

procedure  DrawTopWindow  (theWindow:  GrafPortPtr); 

{callsPthraooronrtdre  dete™lnes  What  type  °f  window  theWindow  is  and 

t,    I   ,        appropriate  procedure  to  draw  its  contents  to  the  current  port 
which  is  now  the  printer  port  created  in  DoPrintltem. )  ^ 

var  myDataHandle:  WindDataH; 

begin    (of  DrawTopWindow) 

myDataHandle  :-  WindDataH  (GetWRefCon  (theWindow) > ■ 
with  myDataHandle""  do 
if  Flag  -  0  then 

Paint It  (pict) 
else 

ShowFont  (theFont,  isMono)  ; 
end;     (of  DrawTopWindow) 

begin    (of  DoPrintltem) 

theWindow  :=  Frontwindow; 
if  theWindow  <>  nil  then 

if  PrJobDialog  (printHndl)  then  begin 
WaitCursor; 

prPort  :=  PrOpenDoc  (printHndl, nil) ; 
PrOpenPage  (prPort,  nil) ; 

DrawTopWindow       (theWindow) ; 
PrClosePage         (prPort) ; 
PrCloseDoc  (prPort); 

PrPicFile  (printHndl,  nil,  nil); 

InitCursor; 
end; 
end;     (of  DoPrintltem) 

procedure  DoSetupItem; 

'0™^  V*   Pa9e  S6tUP  dlal°g  f°r  the  user  to  ch°°^  the  print  mode 
number  of  pages,  etc.  to  print.)  vmu-   moae, 

var  dummy:  boolean; 

begin    (of  DoSetupItem) 

dummy  :-  PrStlDialog  (printHndl); 
end;    {of  DoSetupItem) 

procedure  SetUpDefault; 

(Create  and  initialize  a  THPrint  record  which  is  required  for  all 
printing  operations.) 

begin   (of  SetUpDefault) 

printHndl  :=  PrRecHndl  (NewHandle  (140, 
myMemorylD, 

attrNoCross  +  attrLocked, 
Ptr  (0))); 
PrDefault  (printHndl) ; 
end;     (of  SetUpDefault) 
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PAINT.PAS  (pictures  and  files) 


UNIT  Paint; 


+ 


HodgePodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  1986-87  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Pascal  UNIT  "PAINT.PAS"  :  Bitmapped  picture  load/save  and  window  drawing 


INTERFACE 


HPIntfData, 
HPIntfProc, 
HPIntfPdos, 

Globals, 
Dialog; 


{Hodgepodge  Apple  IIGS  Toolbox  Interface  Units) 


(HodgePodge  Code  Units) 


function  AskUser  :  boolean;  (Load  a  new  picture  from  disk) 

procedure  DoSaveltem;      (If  paint  window  in  front,  do  Std  File  dialog  i   save) 
procedure  Paint;  (Draw  picture  window  contents) 

procedure  Paintlt  (pict:  Handle);  (Do  Paint's  dirty  work) 


IMPLEMENTATION 


($DefProc  ) 

function  OpenFilter  (DirEntry  :  longint)  :  integer; 

(Filter  function  called  by  the  Standard  File  Operations'  SFGetFile 
dialog  to  determine  whether  a  filename  should  be  dimmed  or  not.) 

type 

BytePtr  =  *byte; 
var 

fileTypePtr  :  BytePtr; 

begin   (of  OpenFilter) 

fileTypePtr  :=  Pointer  (DirEntry  +  $10); 

if  (BitAND(FileTypePtrA,$00FF)  -  $C1)  then  (  Unpacked  Picture  File  type  ) 

OpenFilter  :=  2 
else 

OpenFilter  :-  1; 
end;    (of  OpenFilter) 


PAINT.PAS  (pictures  and  files) 
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function  AskUser  :  boolean; 

var  ourTypeList  :  TypeListPtr; 

function  LoadOne  :  boolean; 

(Private  procedure  which  actually  loads  a  picture  from  disk} 

var  openBlk  :  OpenRec; 
readBlk  :  FilelORec; 

begin    (of  LoadOne) 
LoadOne  :=■  false; 

WaitCursor; 

PictHndl  :=  NewHandle  (S8000, 

MyMemorylD, 

0/ 

Ptr  (0)); 
if  isToolError  then 
Exit; 

HLock  (PictHndl); 

openBlk. openPathname  :=  @myReply.fullpathname; 
openBlk. ioBuffer     :=  nil; 
OPEN  (openBlk), - 
if  CheckDiskError  (27)  then 
Exit; 


readBlk. dataBuffer 
readBlk . requestCount 
readBlk . f i 1 eRe  fNum 
READ  (readBlk); 
if  CheckDiskError  (28)  then 
Exit; 

CLOSE  (readBlk) ; 
HUnLock   (PictHndl); 

LoadOne  :-  true; 
end;     (of  LoadOne) 


begin    (of  AskUser) 

SFGetFile  (20, 
20, 

'Load  which  picture:', 
SOpenFilter, 
NIL, 
MyReply) ; 

AskUser  :=  false; 
if  myReply.good  then 
if  LoadOne  then 

AskUser  :-  true; 
end;     (of  AskUser) 


=  PictHndl"; 

-  $8000; 

-  openBlk . openRefNum; 
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procedure  DoSaveltem; 


(This  procedure  is  called  to  save  the  contents  of  a  "Paint"  window 
to  a  disk  file.  NOTE:  This  routine  is  ONLY  called  when  a  "Paint 
window  is  in  front  due  to  enabling/disabling  the  menu  items.) 

var  theWindow:    GrafPortPtr; 
myDataHandle:  WindDataH; 
i:  integer; 


procedure  SaveOne  (pict:  Handle); 

(Private  procedure  which  actually  does  the  picture  save) 


var  destroyBlk 
createBlk 
openBlk 
writeBlk 


PathNameRec; 
FileRec; 
OpenRec; 
FilelORec; 


begin   (of  SaveOne) 

destroyBlk. pathname  :=  "myReply. fullpathname; 
DESTROY  (destroyBlk); 


createBlk. pathname    : 
createBlk. f Access     : 
createBlk . f ileType 
createBlk . auxType 
createBlk . storageType 
createBlk . createDate 
createBlk. createTime 
CREATE  (createBlk) ; 
if  CheckDiskError  (25) 
Exit; 


gmyReply. f ullpathname; 


=  SC3; 

-  $C1; 

-  0; 

-  l; 

=  0; 
=  0; 

then 


(DRbWR,  see  ProDOS16  docs) 
(Unpacked  file) 
(-nothing-) 
(Seedling  file) 


openBlk.openPathname  :=  gmyReply. f ullpathname ; 
openBlk.ioBuffer     :-  nil; 
OPEN  (openBlk) ; 


writeBlk.dataBuffer 
writeBlk . requestCount 
writeBlk . f ileRef Num 
WRITE  (writeBlk) ; 
if  CheckDiskError  (26)  then 
Exit; 

CLOSE  (writeBlk) ; 
end;    (of  SaveOne) 


-  pictA; 

-  $8000; 

-  openBlk.openRefNum; 


begin    (of  DoSaveltem) 

theWindow  :=  FrontWindow; 

myDataHandle  :-  WindDataH  (GetWRefCon  (theWindow)); 

SFPutFile  (20, 

20, 

'Save  which  picture:', 

myDataHandle** .Name, 

15, 

myReply) ; 

if  myReply. good  then  begin 
WaitCursor; 

SaveOne  (myDataHandleAA.pict) ; 
with  myDataHandleAA  do  begin 

(Change  name  of  correct  menu  item:) 
Name  :=  myReply. filename; 


PAINT.PAS  (pictures  and  files) 
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MenuStr  :-  concat  ('  =  ', 

myReply. filename, 
•\N', 

IntToString  (MenuID), 
■\o.'); 

for  i  :=  FirstWind  to  Lastwind  do 

if  WindowList  [i]  =  theWindow  then 
Leave;   (Exit  loop) 
end;36™"6™  (MenuStr'Fi"tWlndItem  +  1);   fNew  menu  name) 

CalcMenuSlze  (0,0,WindowsMenuID) ; 
InitCursor; 
end; 

end;     (of  DoSaveltem) 
procedure  Paint; 

(This  is  a  Definition  Procedure  used  to  draw  the  contents  of  a  Font  window, 

var  tmpPort      :  GrafPortPtr; 
myDataHandle  :  WindDataH; 

begin    {of  Paint) 

tmpPort      :=  GetPort; 

P^nt^f'n  T  "indDataH  <GetwR^Con  (tmpPort)); 
Paintlt  (myDataHandleAA.pict) • 
end;    (of  Paint) 

procedure  Paintlt  (pict:  Handle) ; 

(Procedure  to  actually  draw  the  picture  in  memory  to  the  window.) 

var  srcLoc   :  Loclnfo; 
srcRect  :  Rect; 

begin   (of  Paintlt) 
HLock  (pict) ; 


with  srcLoc  do  begin 
portSCB 
ptrToPixImage 
lwidth 


end, 


=  $0080; 
-  pict'; 
.=  160; 

tetRT^,  (boundsRect,  0,0,  640,  200)  ; 

BoundsRect.vl     :=  o- 


SetRect   (srcRect, 0,0, 640,200) 
PPToPort  (srcLoc, 

srcRect, 

0, 

0, 

srcCopy) ; 

HUnLock  (pict); 
end;    (of  Paintlt) 


END. 
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Appendix  G:  HodgePodge  Source  Code:    Pascal 


GLOBALS.PAS  (global  data) 


UNIT  Globals; 


[+— 


HodgePodge:   An  example  Apple  IIGS  Desktop  application 

Written  by  the  Apple  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  1986-S7  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


Pascal  UNIT  "GLOBALS.PAS"  :  Global  data  structs  and  init  routine 


INTERFACE 


HPIntfData, 
HPIntfProc, 
HPIntfPdos; 


(HodgePodge  Apple  IIGS  Toolbox  Interface  Units) 


ScreenMode 

MaxX 

MaxScan 


$80 
640 
160 


(640  mode) 

(Max  X  clamp  (should  correspond  to  ScreenMode) 

(Max  size  of  scan  line) 


AppleMenuID  =  300 

Aboutltem  -  301 

FileMenuID  -  400 

Openltem  =  401 

Closeltem  -  235 

SaveAsItem  -  403 

ChoosePItem  =  405 

PageSetltem  -  406 

Printltem  =  407 

Quitltem  -  40  9 

EditMenuID  -  500 

Undoltem  =  250 

Cutltem  =  251 

Copyltem  =  252 

Pasteltem  -  253 

Clearltem  =  254 

WindowsMenuID  =  600 

NoWindowsItem  =  601 

FirstWindltem  =  2000 

FontsMenuID  =  700 

Font Item  =  701 

Monoltem  -  702 


(For  DA's) 


(For  DA's) 
(For  DA's) 
(For  DA' s) 
(For  DA's) 
(For  DA's) 


(Allocated  dynamically  starting  at  2000) 


FirstWind 
LastWind 


0; 

15; 


(Lower  bound  of  WindowList) 
(Upper  bound  of  WindowList) 


GLOBALS.PAS  (global  data) 
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type 


KindDataH 
WindDataP 
WindDataRec 


(.. 


-  AWindDataP; 
=  "WindDataRec; 
"  record 

Name:    Str255; 

MenuStr:  Str255; 

MenuID:   integer; 

Flag:    integer; 

case  Integer  of 

0  :  (theFont: 

i  sMono  : 

1  :  (pict: 
end; 


(RefCon  data  for  our  windows) 


.carried  along  with  wind  data) 


(0  =  Paint,  1  -  Font) 

Font ID; 

boolean) ; 
Handle) ; 


MyMemorylD 
Done 

ToolsZeroPage 
Event 

AppleMenuStr 

FileMenuStr 

EditMenuStr 

WindowMenuStr 

FontMenuStr 


NoHindStr 

MonoStr 

ProStr 

LastWindow 

dummy 

DesiredFont 

isMonoFont 

my Reply 

PictHndl 

Wlndex 
WindowList 


PlsWtTemp 
PlsWtltem 

Applelcon 


integer; 

boolean; 

Handle; 

:  WmTaskRec; 

:  Str255; 

:  Str255; 

:  Str255; 

:  Str255; 

:  Str255; 

:  String  [40] 
:  String  [40] 
:  String  [40] 

GrafPortPtr; 

integer; 

Font  ID; 

boolean; 

SFReplyRec; 

Handle; 

integer; 


{Application  ID  assigned  by  Memory  Mgr) 
(True  when  quitting) 

(Handle  to  Zero  page  memory  for  Tools) 
(All  events  are  returned  here) 

(For  creating  menus) 


(Menu  Item  String  for  "No  Windows. 


.") 


{IS!  >^np  Wi^?W  laSt  time  th"u?h  event  1 
(  **  >!<  Possible  compiler  bug?) 
(Indicates  current  selected  font) 
(Flag  indicates  if  mono  spacing  selected) 


(Count  of  number  of  windows  open) 

arrav  mrc™'i  ,  °f  Up  to  15  °Pen  windows) 
array  [firstWind. .lastwind]  of  GrafPortPtr; 

DialogTemplate; 
ItemTemplate; 


record 

boundsRect 
data 

end; 


Rect; 

array  [1..34]  of 
packed  array  [l. 


16]  of  byte; 


procedure  InitGlobals; 
PROCEDURE  HPStuffHex  (thingPtr 


Ptr;  s  :  Str255); 


(Setup  variables) 
(Store  hex) 


Appendix  G:  HodgePodge  Source  Code:    Pascal 


IMPLEMENTATION 


PROCEDURE  HPStuffHex  (thingPtr  :  Ptr;  s  :  Str255) ; 

(>!<  This  routine  will  be  implemented  in  TML  Pascal  VI. 1.   For  now, 
we  define  it  ourselves.   Stuff Hex  stores  bytes  (expressed  as  a  string 
of  hexadecimal  digits)  into  any  data  structure,  and  is  based  on  the 
StuffHex  procedure  in  Macintosh  QuickDraw.   The  resolution  of  this 
routine  is  on  byte  boundaries.) 

var  iterator    :  integer; 
stringlndex  :  integer; 

begin   (of  HPStuffHex) 

for  iterator  :=  0  to  Length  (s)  -  1  do  begin 
stringlndex  :=  (iterator  *  2)  +  1; 

thingPtr'  :=  Hex2Int  (StringPtr  (longint  (@s)  +  stringlndex) ,2) ; 
thingPtr  :=  pointer  (longint  (thingPtr)  +  1) ; 
end; 
end;     (of  HPStuffHex) 


procedure  InitGlobals; 

(Initialize  global  data  variables,  including  the  PlsWtTemp  used  by 
ShowPleaseWaitDialog,  the  menu  strings  used  by  the  menu  bar  setup 
routines  in  MENU. PAS,  and  the  apple  icon  used  by  the  "about  — " 
item  dialog  routine  in  DIALOG. PAS) 

begin   (of  InitGlobals) 

with  PlsWtTemp  do  begin 


SetRect 

dtVisible 

dtRefCon 

dtltemList 

dtltemList 


(dtBoundsRect,120,30,520,80) ; 

:=  true; 

:  =  0; 

[0]  :-  pointer  (0);  (We  will  insert  ptr  to  item  here) 

[1]  :-  nil;        (Null-terminated) 


end; 


AppleMenuStr  :=  concat  ( 
FileMenuStr   :=  concat  ( 


EditMenuStr  :=  concat  ( 


WindowMenuStr 
FontMenuStr 


concat ( 
concat 


»@\N300X\0', 

—About  Hodgepodge. ..\N301\01, 

— \N302D\0. '); 

»  File  \N400\0', 

— Open...\N401*Oo\0\ 

— Close\N255D\0\ 

—Save  As.  ..\N403D\0', 

— \N404D\0', 

--Choose  Printer... \N405\0', 

— Page  Setup. . .\N406D\0' , 

—Print . . .  \N407*PpD\0  ' , 

\N408D\0\ 

— Quit\N409*Qq\0. ' )  ; 
»  Edit  \N500D\0', 
==Undo\N250*Zz\0', 

\N501D\01, 

~Cut\N251*Xx\0', 
==Copy\N252*Cc\0' , 
— Paste\N253*Vv\0 ' , 
~Clear\N254\0."); 
»  Window  \N600D\0', 
—  No  Windows  Allocated\N601D\0. ') ; 
('»  Fonts  \N700\0\ 
—Display  Font...\N701*Ff\0', 
==Display  Font  as  Mono-spaced\N702*Mm\0. ' ) ; 


LastWindow 


:=  nil; 


GLOBALS.PAS  (global  data) 


M^O 


NoWindStr 


:=  '==No  Windows  Allocated\N601D\0. '; 


MonoStr 

ProStr 

isMonoFont 


=  ' -Display  Font  as  Mono-spaced'; 
-  '=Display  Font  as  Proportional'; 
=  false; 


with  DesiredFont  do  begin 


famNum 
fontStyle 
font  Size 


SFFFE; 
0; 


WIndex 


0; 


{No  windows  open  yet} 


SetRect 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 

HPStuffHex 


(Applelcon.boundsRect 
( SAppl el con . dat  a [ 1 ] 
(SApplelcon.data [2] 
(SApplel con . data [ 3 ] 
(SApplelcon.data [4] 
(SApplelcon.data [5] 
( SAppl el con . dat  a [ 6 ] 
( S Appl el con . dat  a [ 7 ] 
( SAppl el con . dat  a [ 8 ] 
(SApplel con . data [ 9 ] 
(SApplelcon.data [10 
(SApplelcon.data [11 
( SAppl el con . dat  a [ 1 2 
(@AppleIcon.data[13 
(SApplelcon.data [14 
(SApplelcon.data [15 
(SApplel con . data [ 1 6 
(SApplelcon.data [17 
(SApplelcon.data [18 
(SApplelcon.data [19 
(SApplelcon.data [20 
(6AppleIcon.dat a [21 
(SApplelcon.data [22 
(SApplelcon.data [23 
(SApplelcon.data [24 
(SApplelcon.data [25 
(SApplelcon.data [26 
(SApplelcon.data [27 
( SAppl  el  con .  dat  a  [  2  8 
(SApplelcon.data [29 
(8AppleIcon.dat a [30 
(SApplelcon.data [31 
(SApplelcon.data [32 
(SApplelcon.data [33 
(SApplelcon.data [34 


0,0,64,34); 

'00000000000000000000000000000000' 
i OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO ' 
'0FO00OO00OOO00OO00OO000OO00OO0F0' 
1 OF0FFFFFFFFFFFFFFFFFFFFFFFFFF0FO ' 
1 0F0FFFFFFFFFFFFFFFFFF88FFFFFF0F0 ■ 
' OF0FFFFFFFFFFFFFFFF8888FFFFFF0FO ' 
1 0FOFFFFFFFFFFFFFFF88888FFFFFFOF0 ' 
1 0FOFFFFFFFFFFFFFF88888FFFFFFFOF0 ' 
1 0FOFFFFFFFFFFFFF888888FFFFFFFOF0 ' 
1 OF0FFFFFFFFFFFFF88888FFFFFFFF0FO ' 
' OF0FFFFFFFFFFFFF8888FFFFFFFFF0FO ' 
' 0F0FFFFFF8888FFF88FF8888FFFFF0F0 ' 
' 0F0FFFF88888888FFF88888888FFF0F0 ' 
'0FOFFF888888888888888888888FFOF0' 
' OFOFFeeeeeeeeeeeeeeeeeeeeFFFFOFO ' 
' OFOFFeeeeeeeeeeeeeeeeeeeFFFFFOFO ■ 
' OFOFFeeeeeeeeeeeeeeeeeeFFFFFFOFO ■ 
'0F0FF666666666666666666FFFFFF0F0' 
'0F0FF666666666666666666FFFFFF0F0' 
•0F0FF666666666666666666FFFFFF0F0' 
'0F0FF4444444444444444444FFFFF0F0' 
'0FOFF44444444444444444444FFFFOF0' 
'0FOFFF444444444444444444444FF0FO1 
'0F0FFF555555555555555555555FF0F0' 
'OF0FFF555555555555555555555FF0FO' 
•OF0FFFF5555555555555555555FFFOFO' 
•OF0FFFF1111111111111111111FFFOF0' 
•0F0FFFFF11111111111111111FFFF0F0' 
' 0F0FFFFFF111111FFF111111FFFFF0F0 ' 
' 0F0FFFFFFF1111FFFFF1111FFFFFF0F0 ' 
' 0FOFFFFFFFFFFFFFFFFFFFFFFFFFF0FO • 
'OFO00OO00OOO00OO0OOO0OOOO0OO00FO' 
' OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO ' 
'00000000000000000000000000000000' 


end; 


(of  InitGlobals) 
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Appendix  G:  HodgePodge  Source  Code:    Pascal 


Glossary 


absolute:  Characteristic  of  a  load  segment  or 
other  program  code  that  must  be  loaded  at  a 
specific  address  in  memory  and  never  moved. 
Compare  relocatable,  position-independent. 

absolute  addressing:  an  addressing  mode  in 
which  instruction  operands  are  interpreted  as 
literal  addresses. 

access  (or  access  byte):  An  attribute  of  a  ProDOS 
file  that  controls  whether  the  file  may  be  read 
from,  written  to,  renamed,  or  backed  up. 

accumulator:  The  register  in  a  computer's  central 
processor  or  microprocessor  where  most 
computations  are  performed. 

activate:  To  make  active.  A  control  or  window 
may  be  activated.  Compare  enable. 

activate  event:  a  window  event  that  occurs  when  a 
window  is  made  either  active  or  inactive. 

active:  Able  to  respond  to  the  user's  mouse  or 
keyboard  actions.  Controls  and  windows  that  are 
active  are  displayed  differently  from  inactive 
items. 

ADB:  See  Apple  Desktop  Bus. 

address  bus:  The  bus  that  carries  addresses  from 
the  CPU  to  components  under  its  control. 


advanced  linker  (APW):  One  aspect  of  the  linker 
supplied  with  APW.  The  operation  of  the 
advanced  linker  is  programmable.  Compare 
standard  linker. 

alert:  A  warning  or  report  of  an  error  in  the  form 
of  an  alert  box,  a  sound  from  the  computer's 
speaker,  or  both. 

alert  box:  A  special  type  of  dialog  box  that 
appears  on  the  screen  to  give  a  warning  or  to 
report  an  error  message  during  use  of  an 
application. 

alert  window:  The  window  in  which  an  alert  box 
appears.  One  of  the  two  predefined  window 
formats.  Compare  document  window. 

analog  RGB:  A  type  of  color  video  consisting  of 
separate  analog  signals  from  the  red,  green,  and 
blue  color  primaries.  The  intensity  of  each 
primary  can  vary  continuously,  making  possible 
many  shades  and  tints  of  colors.  Compare  TTL 
RGB. 

Apple  Desktop  Bus  (ADB):  An  input  bus,  with  its 
own  protocol  and  electrical  characteristics,  that 
provides  a  method  of  connecting  input  devices 
such  as  keyboards  and  mouse  devices  to  personal 
computers. 

Apple  Desktop  Bus  Tool  Set:  The  Apple  II GS  tool 
set  that  facilitates  an  application's  interaction 
with  devices  connected  to  the  Apple  Desktop 
Bus. 
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Apple  key:  A  modifier  key  on  the  Apple  IIGS 
keyboard,  marked  with  both  an  Apple  icon  and  a 
spinner,  the  icon  used  on  the  equivalent  key  on 
some  Macintosh  keyboards.  It  performs  the  same 
functions  as  the  Open  Apple  key  on  standard 
Apple  II  machines. 

AppleTalk  network:  A  local  area  network 
developed  by  Apple  Computer,  Inc. 

Apple  II:  A  family  of  computers,  including  the 
original  Apple  II,  the  Apple  II  Plus,  the  Apple  lie, 
the  Apple  lie,  and  the  Apple  IIGS.  Compare 
standard  Apple  IL 

Apple  He:  A  transportable  personal  computer  in 
the  Apple  II  family,  with  a  disk  drive,  serial  ports, 
and  80-column  display  capability  built  in. 

Apple  He:  A  personal  computer  in  the  Apple  II 
family  with  seven  expansion  slots  and  an 
auxiliary  memory  slot  that  allow  the  user  to 
enhance  the  computer's  capabilities  with 
peripheral  memory  and  video  enhancement 
cards. 

Apple  IIGS:  The  most  advanced  computer  in  the 
Apple  II  family.  It  features  expanded  memory, 
advanced  sound  and  graphics,  and  the  Apple 
IIGS  Toolbox  of  programming  routines. 

Apple  IIGS  Debugger:  A  65816  machine  language 
code  debugger  for  the  Apple  IIGS  computer. 

Apple  IIGS  Programmer's  Workshop  (APW):  A 

multilanguage  development  environment  for 
writing  Apple  IIGS  desktop  applications. 

Apple  IIGS  Toolbox:  An  extensive  set  of  routines 
that  facilitate  writing  desktop  applications  and 
provide  easy  program  access  to  many  Apple  IIGS 
hardware  and  firmware  features. 

Apple  n  Plus:  A  personal  computer  in  the  Apple 
II  family  with  expansion  slots  that  allow  the  user 
to  enhance  the  computer's  capabilities  with 
peripheral  cards. 


application:  A  stand-alone  program  that 
performs  a  specific  function,  such  as  word- 
processing,  drawing,  or  telecommunications. 
Compare,  for  example,  desk  accessory  or  device 
driver. 

application-defined  event:  Any  of  four  types  of 
events  available  for  applications  to  define  and 
respond  to  as  desired. 

application  prefix:  The  ProDOS  16  prefix  number 

1  / .  It  specifies  the  directory  of  the  currently 
running  application. 

application  window:  A  window  in  which  an 
application's  document  appears. 

APW:  See  Apple  IIGS  Programmer's  Workshop. 

APW  Assembler:  The  65816  assembly-language 
assembler  provided  with  the  Apple  IIGS 
Programmer's  Workshop. 

APW  C  Compiler:  The  C-language  compiler 
provided  with  the  Apple  IIGS  Programmer's 
Workshop. 

APW  Editor:  The  program  within  the  Apple  IIGS 
Programmer's  Workshop  that  allows  you  to  enter, 
modify,  and  save  source  fdes  for  all  APW 
languages. 

APW  Linker:  The  linker  supplied  with  the 
Apple  IIGS  Programmer's  Workshop. 

APW  Shell:  The  programming  environment  of 
the  Apple  IIGS  Programmer's  Workshop — it 
provides  facilities  for  file  manipulation  and 
program  execution,  and  supports  shell 
applications. 

APW  utility  program:  Any  of  various  Shell 
applications  supplied  with  the  Apple  IIGS 
Programmer's  Workshop  that  function  as  APW 
Shell  commands. 

arc:  A  portion  of  an  oval;  one  of  the  fundamental 
shapes  drawn  by  QuickDraw  II. 

A  register:  See  accumulator. 
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Glossary 


ascent:  In  a  font,  the  distance  between  the  base 
line  and  the  ascent  line. 

ascent  line:  A  horizontal  line  that  coincides  with 
the  tops  of  the  tallest  characters  in  a  font.  See 
also  base  line,  descent  line. 

ASCII:  Acronym  for  American  Standard  Code  for 
Information  Interchange,  pronounced  "ASK-ee." 
A  code  in  which  the  numbers  from  0  to  127  stand 
for  text  characters.  ASCII  code  is  used  to 
represent  text  inside  a  computer  and  to  transmit 
text  between  computers  or  between  a  computer 
and  a  peripheral  device. 

assembler:  A  language  translator  that  converts  a 
program  written  in  assembly  language  into  an 
equivalent  program  in  machine  language.  The 
opposite  of  a  disassembler. 

attributes  'word:  Determines  how  memory  blocks 
are  allocated  and  maintained.  Most  of  the 
attributes  are  defined  at  allocation  time  and  can't 
be  changed  after  that;  other  attributes  can  be 
modified  after  allocation. 

auto-key:  A  keyboard  feature  and  an  event  type,  in 
which  a  key  being  held  down  continuously  is 
interpreted  as  a  rapid  series  of  identical 
keystrokes. 

auxID:  A  subfield  of  the  User  ID.  An  application 
may  place  any  value  it  wishes  into  the  auxID 
field. 

auxiliary  type:  A  secondary  classification  of 
ProDOS  files.  A  file's  auxiliary  type  field  may 
contain  information  of  use  to  the  applications 
that  read  it.  Compare  file  type. 

background:  The  pixels  within  a  character  or 
other  screen  object  that  are  not  part  of  the 
object  itself. 

background  color:  The  color  of  background 
pixels  in  text;  by  default  it  is  black. 

background  pattern:  The  pattern  QuickDraw  II 
uses  to  erase  objects  on  the  screen. 


background  pixels:  In  a  character  image,  the 
pixels  that  are  not  part  of  the  character  itself. 

background  procedure:  A  procedure  run  by  the 
Print  Manager  whenever  the  Print  Manager  has 
directed  output  to  the  printer  and  is  waiting  for 
the  printer  to  finish. 

backup  bit:  A  bit  in  a  file's  access  byte  that  tells 
backup  programs  whether  the  file  has  been 
altered  since  the  last  time  it  was  backed  up. 

bank:  A  64K  (65,536-byte)  portion  of  the  Apple 
IIGS  internal  memory.  An  individual  bank  is 
specified  by  the  value  of  the  65816 
microprocessor's  bank  register. 

bank-switched  memory:  On  Apple  II  computers, 
the  part  of  language  card  memory  in  which  two 
4K  portions  of  memory  share  the  same  address 
range  ($D000  to  $DFFF). 

bank  $00:  The  first  bank  of  memory  in  the  Apple 
IIGS.  In  emulation  mode,  it  is  equivalent  to  main 
memory  in  an  Apple  lie  or  Apple  lie  computer. 

base  fine:  A  horizontal  line  that  coincides  with 
the  bottom  of  the  main  body  of  each  character 
in  a  font.  Character  descenders  extend  below  the 
base  line. 

BASIC:  Acronym  for  Beginners  All-purpose 
Symbolic  Instruction  Code.  BASIC  is  a  high-level 
programming  language  designed  to  be  easy  to 
learn.  Applesoft  BASIC  is  built  into  the  Apple 
IIGS  firmware. 

batch:  A  mode  of  executing  a  computer  program 
in  which  all  code  and  data  required  by  the 
program  are  loaded  into  the  computer  at  the 
beginning,  the  program  is  run,  and  all  results  are 
output  at  the  end.  Batch  mode  is  non-interactive. 

binary  file:  (1)  A  file  whose  data  is  to  be 
interpreted  in  binary  form.  Machine-language 
programs  and  pictures  are  stored  in  binary  files. 
Compare  text  file.  (2)  A  file  in  binary  file  format. 
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binary  file  format:  The  ProDOS  8  loadable  file 
format,  consisting  of  one  absolute  memory 
image  along  with  its  destination  address.  A  file  in 
binary  file  format  has  ProDOS  file  type  $06  and 
is  referred  to  as  a  BIN  file.  The  System  Loader 
cannot  load  BIN  files. 

bit:  A  contraction  of  binary  digit,  the  smallest 
representation  of  data  in  a  digital  computer. 

bit  plane:  A  method  of  representing  images  in 
computer  memory.  In  a  bit  plane,  consecutive 
bits  in  memory  specify  adjacent  pixels  in  the 
image;  if  more  than  one  bit  is  required  to 
completely  specify  the  state  of  a  pixel,  more  than 
one  bit  plane  is  used  for  the  image.  Compare 
chunky  pixels. 

block:  (1)  A  unit  of  data  storage  or  transfer, 
typically  512  bytes.  (2)  A  contiguous  region  of 
computer  memory  of  arbitrary  size,  allocated  by 
the  Memory  Manager.  Also  called  a  memory 
block. 

block  device:  A  device  that  transfers  data  to  or 
from  a  computer  in  multiples  of  one  block  (512 
bytes)  of  characters  at  a  time.  Disk  drives  are 
block  devices.  Also  called  block  I/O  device. 

Boolean  logic:  A  mathematical  system  in  which 
every  expression  evaluates  to  one  of  two  values, 
usually  referred  to  as  TRUE  or  FALSE. 

Boolean  variable:  A  variable  that  can  have  one 
of  two  values,  usually  referred  to  as  TRUE  or 
FALSE. 

boot  prefix:  The  ProDOS  16  prefix  number  */.  It 
specifies  the  name  of  the  volume  from  which  the 
currently  running  version  of  ProDOS  16  was 
started  up. 

boundary  rectangle:  A  rectangle,  defined  as  part 
of  a  QuickDraw  II  Loclnfo  record,  that  encloses 
the  active  area  of  the  pixel  image  and  imposes  a 
coordinate  system  on  it.  Its  upper-left  corner  is 
always  aligned  on  the  first  pixel  in  the  pixel  map. 

boundsRect:  The  GrafPort  field  that  defines  the 
port's  boundary  rectangle. 


breakpoint:  A  machine-language  instruction  in  a 
program  that  causes  execution  to  halt. 

buffer:  A  holding  area  of  the  computer's  memory 
where  information  can  be  stored  by  one 
program  or  device  and  then  read,  perhaps  at  a 
different  rate,  by  another;  for  example,  a  print 
buffer. 

Busy  flag:  A  feature  that  informs  the  Scheduler 
whether  a  currently  needed  resource  is  busy  or 
available. 

button:  (1)  A  pushbutton-like  image  in  a  dialog 
box  where  the  user  clicks  to  designate,  confirm, 
or  cancel  an  action.  Compare  radio  button, 
check  box.  (2)  A  button  on  a  mouse  or  other 
pointing  device. 

byte:  A  unit  of  information  consisting  of  eight 
bits.  A  byte  can  have  any  value  between  0  and 
255,  which  may  represent  an  instruction,  letter, 
number,  punctuation  mark,  or  other  character. 
See  also  bit,  kilobyte,  megabyte. 

C:  A  high-level  programming  language.  One  of 
the  languages  available  for  the  Apple  IIGS 
Programmer's  Workshop. 

cancel:  To  stop  an  operation,  such  as  the  setting 
of  page-setup  values  in  a  dialog  box,  without 
saving  any  results  produced  up  to  that  point. 

Cancel:  One  of  two  predefined  item  ID  numbers 
for  dialog  box  buttons  (Cancel  =  2).  Compare 
OK. 

card:  See  peripheral  card. 

caret:  A  symbol  that  indicates  where  something 
should  or  will  be  inserted  in  text.  On  the  screen  it 
designates  the  insertion  point,  and  is  usually  a 
vertical  bar  (I). 

carry  flag:  A  status  bit  in  the  microprocessor 
indicating  whether  an  accumulator  calculation 
has  resulted  in  a  carry  out  of  the  register. 

CDA:  See  classic  desk  accessory. 

c  flag:  See  carry  flag. 
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character:  Any  symbol  that  has  a  widely 
understood  meaning  and  thus  can  convey 
information.  Some  characters — such  as  letters, 
numbers,  and  punctuation — can  be  displayed  on 
the  monitor  screen  and  printed  on  a  printer. 
Most  characters  are  represented  in  the  computer 
as  one-byte  values. 

character  device:  A  device  that  transfers  data  to 
or  from  a  computer  as  a  stream  of  individual 
characters.  Keyboards  and  printers  are  character 
devices. 

character  image:  An  arrangement  of  bits  that 
defines  a  character  in  a  font. 

character  origin:  The  point  on  the  base  line  used 
as  a  reference  location  for  drawing  a  character. 

character  width:  The  number  of  pixels  the  pen 
position  is  to  be  advanced  after  the  character  is 
drawn. 

check  box:  A  small  box  associated  with  an  option 
in  a  dialog  box.  When  the  user  clicks  the  check 
box,  that  may  change  the  option  or  affect  related 
options. 

Choose  Printer:  A  part  of  the  Print  Manager  that 
lets  the  user  select  a  printer  or  port  for  printing. 

chunkiness:  The  number  of  bits  required  to 
describe  the  state  of  a  pixel  in  a  pixel  image. 

chunky  pixels:  A  method  of  representing  images 
in  computer  memory.  In  chunky  pixel 
organization,  a  number  of  consecutive  bits  in 
memory  combine  to  specify  the  state  of  a  single 
pixel  in  the  image.  Consecutive  groups  of  bits 
(the  size  of  the  group  is  equal  to  the  image's 
chunkiness)  define  adjacent  pixels  in  the  image. 
Compare  bit  plane. 

clamp  values:  The  x-  and  y-limits,  in  terms  of 
pixels,  on  cursor  position  controlled  by  mouse 
movement. 


classic  desk  accessory  (CDA):  Desk  accessories 
designed  to  execute  in  a  non-desktop,  non-event- 
based  environment.  Compare  new  desk 
accessory. 

click:  To  position  the  pointer  on  something,  and 
then  to  press  and  quickly  release  the  button  on 
the  mouse  or  other  pointing  device. 

clip:  To  restrict  drawing  to  within  a  particular 
boundary;  any  drawing  attempted  outside  that 
boundary  does  not  occur. 

Clipboard:  The  holding  place  for  what  the  user 
last  cut  or  copied;  a  buffer  area  in  memory. 
Information  on  the  Clipboard  can  be  inserted 
(pasted)  into  documents.  In  memory,  the 
contents  of  the  Clipboard  are  called  the  desk 
scrap. 

clipping  region:  The  region  to  which  an 
application  limits  drawing  in  a  GrafPort. 

clock:  (1)  The  timing  circuit  that  controls 
execution  of  a  microprocessor.  Also  called  the 
system  clock.  (2)  An  integrated  circuit,  often  with 
battery-backup  memory,  that  gives  the  current 
date  and  time.  Also  called  the  clock-calendar. 

clock  speed:  The  frequency  of  the  system  clock 
signal  in  megahertz. 

close  box:  The  small  white  box  on  the  left  side  of 
the  title  bar  of  an  active  window.  Clicking  it 
closes  the  window. 

CMOS:  Abbreviation  for  complementary  metal- 
oxide  semiconductor,  one  of  several  methods  of 
making  integrated  circuits  out  of  silicon.  CMOS 
devices  are  characterized  by  their  low  power 
consumption.  CMOS  techniques  are  derived 
from  MOS  techniques. 

color  table:  One  of  16  possible  lookup  tables  in 
Apple  IIGS  memory,  that  lists  the  available  color 
values  for  a  scan  line. 
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command  line:  (1)  In  APW,  the  line  of  text  with 
which  the  user  invokes  a  procedure  or  function 
or  executes  a  program.  The  command  line  often 
includes  both  the  name  of  the  function  to 
execute  and  a  list  of  parameters  to  be  passed  to 
the  function.  (2)  The  line  on  the  screen  on  which 
a  command  is  entered. 

command-line  interface:  The  type  of  interface 
between  user  and  program  in  which  information 
is  passed  in  a  command  line. 

compaction:  The  rearrangement  of  allocated 
blocks  in  memory  to  open  up  larger  contiguous 
areas  of  free  space. 

compiler:  A  program  that  produces  object  files 
(containing  machine-language  code)  from  source 
files  written  in  a  high-level  language  such  as  C. 
Compare  assembler. 

content  region:  The  area  in  a  window  in  which  an 
application  presents  information  to  the  user. 

control:  An  object  in  a  window  with  which  the 
user,  using  the  mouse,  can  cause  instant  action 
with  visible  results  or  change  settings  to  modify  a 
future  action. 

controlling  program:  A  program  that  loads  and 
runs  other  programs,  without  itself  leaving 
memory.  A  controlling  program  is  responsible 
for  shutting  down  its  subprograms  and  freeing 
their  memory  space  when  they  are  finished.  A 
shell,  for  example,  is  a  controlling  program. 

Control  Manager:  The  Apple  IIGS  tool  set  that 
manages  controls. 

Control  Panel:  A  desk  accessory  that  lets  the  user 
change  certain  system  parameters,  such  as 
speaker  volume,  display  colors,  and  configuration 
of  slots  and  ports. 

coordinate  plane:  A  two-dimensional  grid 
defined  by  QuickDraw  II.  All  drawing  commands 
are  located  in  terms  of  coordinates  on  the  grid. 


coordinates:  X-Y  locations  on  the  QuickDraw  II 
coordinate  plane.  Most  QuickDraw  routines 
accept  and  return  coordinates  in  the  order  (Y,X). 

copy:  To  duplicate  something  by  selecting  it  and 
choosing  Copy  from  the  Edit  menu.  A  copy  of 
the  selected  portion  is  placed  on  the  Clipboard, 
without  affecting  the  original  selection. 

creation  date:  An  attribute  of  a  ProDOS  file;  it 
specifies  the  date  on  which  the  file  was  first 
created. 

creation  time:  An  attribute  of  a  ProDOS  file;  it 
specifies  the  time  at  which  the  file  was  first 
created. 

C  string:  An  ASCII  character  string  terminated  by 
a  null  character  (ASCII  value  =  0). 

cursor:  A  symbol  displayed  on  the  screen 
marking  where  the  user's  next  action  will  take 
effect  or  where  the  next  character  typed  from  the 
keyboard  will  appear. 

cut:  To  remove  something  by  selecting  it  and 
choosing  Cut  from  the  Edit  menu.  The  cut 
portion  is  placed  on  the  Clipboard. 

data  area:  A  document  as  viewed  in  a  window. 
The  data  area  is  the  entire  document,  only  a 
portion  of  which  (the  visible  region)  may  be 
seen  in  the  window  at  any  one  time. 

data  bank  register:  A  register  in  the  65816 
processor  that  contains  the  high-order  byte  of 
the  24-bit  address  that  references  data  in 
memory. 

data  bus:  A  set  of  the  electrical  conductors  that 
carry  data  from  one  internal  part  of  the 
computer  to  another. 

data  structure:  A  specifically  formatted  item  of 
data  or  a  form  into  which  data  may  be  placed. 

DB  register:  See  data  bank  register. 
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debugger:  A  utility  used  for  software  development 
that  allows  you  to  analyze  a  program  for  errors 
that  cause  it  to  malfunction.  For  example,  it  may 
allow  you  to  step  through  execution  of  the 
program  one  instruction  at  a  time. 

default  prefix:  The  pathname  prefix  attached  by 
ProDOS  16  to  a  partial  pathname  when  no  prefix 
number  is  supplied  by  the  application.  The 
default  prefix  is  equivalent  to  prefix  number  0/. 

definition  procedure:  A  routine  that  defines  the 
characteristics  of  some  desktop  feature  such  as  a 
window  or  control.  For  example,  TaskMaster 
needs  a  pointer  to  a  window-content  dejiniton 
procedure  (wContDefP roc)  in  order  to  draw  the 
contents  of  windows  that  it  manipulates. 

DefProa  See  definition  procedure. 

dereference:  To  substitute  a  pointer  for  a 
memory  handle,  or  a  value  for  a  pointer.  When 
you  dereference  a  memory  block's  handle,  you 
access  the  block  directly  (through  its  master 
pointer)  rather  than  indirectly  (through  its 
handle). 

descender:  Any  part  of  a  character  that  lies 
below  the  base  line  (such  as  the  tail  on  a  lower- 
case "p")  • 

descent:  In  a  font,  the  distance  between  the  base 
line  and  the  descent  line. 

descent  line:  A  horizontal  line  that  coincides  with 
the  bottom  of  the  character  descender  that 
extends  farthest  below  the  base  line.  See  also 
ascent  line,  font  height 

desk  accessory:  A  "mini-application"  that  is 
available  to  the  user  regardless  of  whether 
another  application  is  running.  The  Apple  IIGS 
supports  two  types  of  desk  accessories:  classic 
desk  accessories  and  new  desk  accessories. 

desk  accessory  event:  An  event  that  occurs  when 
the  user  enters  the  special  keystroke 
(Control-Apple-Escape)  to  invoke  a  classic  desk 
accessory. 


Desk  Manager:  The  Apple  IIGS  tool  set  that 
executes  desk  accessories  and  enables 
applications  to  support  them. 

desk  scrap:  A  piece  of  data,  maintained  by  the 
Scrap  Manager,  taken  from  one  application  and 
available  for  insertion  into  another. 

desktop:  The  visual  interface  between  the 
computer  and  the  user — the  menu  bar  and  the 
gray  (or  solid-colored)  area  on  the  screen.  In 
many  applications  the  user  can  have  a  number  of 
documents  on  the  desktop  at  the  same  time. 

desktop  interface:  See  desktop. 

destination:  See  destination  location. 

destination  location:  The  location  (memory 
buffer  or  portion  of  the  QuickDraw  II  coordinate 
plane)  to  which  data  such  as  text  or  graphics  is 
copied.  Compare  source  location.  See  also 
destination  rectangle. 

destination  rectangle:  The  rectangle  (on  the 
QuickDraw  II  coordinate  plane)  in  which  text  or 
graphics  are  drawn  when  transferred  from 
somewhere  else.  Compare  source  rectangle. 

development  environment:  A  program  or  set  of 
programs  that  allows  you  to  write  applications.  It 
typically  consists  of  a  text  editor,  an  assembler  or 
compiler,  a  linker,  and  support  programs  such  as 
a  debugger. 

device:  A  piece  of  hardware  used  in  conjunction 
with  a  computer  and  under  the  computer's 
control.  Also  called  a  peripheral  device  because 
such  equipment  is  often  physically  separate  from, 
but  attached  to,  the  computer. 

device  driver:  A  program  that  handles  the 
transfer  of  data  to  and  from  a  peripheral  device, 
such  as  a  printer  or  disk  drive. 

device-driver  event:  An  event  generated  by  a 
device  driver. 
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dial:  An  indicator  on  the  screen  that  displays  a 
quantative  setting  or  value.  Usually  found  in 
analog  form,  such  as  a  fuel  gauge  or 
thermometer.  A  scroll  bar  is  a  standard  type  of 
dial. 

dialog:  See  dialog  box. 

dialog  box:  A  box  on  the  screen  that  contains  a 
message  requesting  more  information  from  the 
user.  See  also  alert. 

Dialog  Manager:  The  Apple  IIGS  tool  set  that 
manipulates  dialog  boxes  and  alerts,  which 
appear  on  the  screen  when  an  application  needs 
more  information  to  carry  out  a  command  or 
when  the  user  needs  to  be  notified  of  an 
important  situation. 

dialog  record:  Information  describing  a  dialog 
window  that  is  maintained  by  the  Dialog 
Manager. 

dialog  window:  The  window  in  which  a  dialog  box 
appears. 

digital  oscillator  chip  (DOC):  An  integrated 
circuit  in  the  Apple  IIGS  that  contains  32  digital 
oscillators,  each  of  which  can  generate  a  sound 
from  stored  digital  waveform  data. 

digital  RGB  video  monitor:  A  type  of  RGB  video 
display  in  which  the  intensities  of  the  red,  green, 
and  blue  signals  are  fixed  at  discrete  values. 

dim:  On  the  Apple  IIGS  desktop,  to  display  a 
control  or  menu  item  in  gray  rather  than  black, 
to  notify  the  user  that  the  item  is  inactive. 

direct  page:  A  page  (256  bytes)  of  bank  $00  of 
Apple  IIGS  memory,  any  part  of  which  can  be 
addressed  with  a  short  (one-byte)  address 
because  its  high-order  address  byte  is  always  $00 
and  its  middle  address  byte  is  the  value  of  the 
65816  direct  register.  Co-resident  programs  or 
routines  can  have  their  own  direct  pages  at 
different  locations.  The  direct  page  corresponds 
to  the  6502  processor's  zero  page.  The  term 
direct  page  is  often  used  informally  to  refer  to 
any  part  of  the  direct-page/stack  space. 


direct-page/stack  segment:  A  program  segment 
that  is  used  to  initialize  the  size  and  contents  of 
an  application's  stack  and  direct  page. 

direct-page/stack  space:  A  single  block  of 
memory  that  contains  an  application's  stack  and 
direct  page. 

direct  register:  A  hardware  register  in  the  65816 
processor  that  specifies  the  start  of  the  direct 
page. 

disable:  To  make  unresponsive  to  user  actions.  A 
dialog  box  control  that  is  disabled  does  nothing 
when  selected  or  manipulated  by  the  user.  In 
appearance,  however,  it  is  identical  to  an  enabled 
control.  Compare  inactive. 

disabled  menu:  A  menu  that  can  be  pulled  down, 
but  whose  items  are  dimmed  and  not  selectable. 

disassembler:  A  program  that  converts  machine- 
language  code  in  memory  into  assembly- 
language  instructions.  Opposite  of  assembler. 

disk  operating  system:  An  operating  system 
whose  principle  function  is  to  manage  disk-based 
file  access. 

disk  port:  The  connector  on  the  rear  panel  of  the 
Apple  IIGS  for  attaching  disk  drives. 

Disk  II:  A  type  of  disk  drive  made  and  sold  by 
Apple  Computer,  Inc.,  for  use  with  the  Apple  II,  II 
Plus,  and  lie  computers.  It  uses  5.25-inch  disks. 

display  mode:  A  specification  for  the  way  in 

which  a  video  display  functions,  including  such 
parameters  as  whether  displaying  text  or 
graphics,  available  colors,  and  number  of  pixels. 
The  Apple  IIGS  has  two  text  display  modes  (40 
column  and  80  column),  two  standard  Apple  II 
graphics  display  modes  (Hi-Res  and  Double 
Hi-Res),  and  two  new  Super  Hi-Res  graphics 
display  modes  (320  mode  and  640  mode). 

display  rectangle:  A  rectangle  that  determines 
where  an  item  is  displayed  within  a  dialog  box. 
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dispose:  To  permanently  deallocate  (a  memory 
block).  The  Memory  Manager  disposes  of  a 
memory  block  by  removing  its  master  pointer. 
Any  handle  to  that  pointer  will  then  be  invalid. 
Compare  purge. 

dithering:  A  technique  for  alternating  the  values 
of  adjacent  pixels  to  create  the  optical  effect  of 
intermediate  values.  Dithering  can  give  the  effect 
of  shades  of  gray  on  a  black-and-white  display,  or 
more  colors  on  a  color  display. 

DOC:  See  digital  oscillator  chip. 

document:  A  file  created  by  an  application. 

document  window:  A  window  that  displays  a 
document.  One  of  the  two  predefined  window 
formats.  Compare  alert  window. 

dormant:  Said  of  a  program  that  is  not  being 
executed,  but  whose  essential  parts  are  all  in  the 
computer's  memory.  A  dormant  program  may 
be  quickly  restarted  because  it  need  not  be 
reloaded  from  disk. 

double-click:  To  position  the  pointer  where  you 
want  an  action  to  take  place,  and  then  press  and 
release  the  mouse  button  twice  in  quick 
succession  without  moving  the  mouse. 

draft  printing:  The  print  method  that  the 
LaserWriter  uses.  QuickDraw  II  calls  are  converted 
direcUy  into  command  codes  the  printer 
understands,  which  are  then  immediately  used  to 
drive  the  printer.  Compare  spool  printing. 

drag:  To  position  the  pointer  on  something, 
press  and  hold  the  mouse  button,  move  the 
mouse,  and  release  the  mouse  button.  When  you 
release  the  mouse  button,  you  either  confirm  a 
menu  selection  or  move  an  object  to  a  new 
location. 

drag  area:  A  subregion  in  a  window  (usually  the 
title  bar)  in  which  the  mouse  pointer  must  be 
placed  before  the  user  can  drag  the  window. 

draw:  In  QuickDraw  II,  to  color  pixels  in  a  pixel 
image. 


drawing  environment:  The  complete  description 
of  how  and  where  drawing  may  take  place.  Every 
open  window  on  the  Apple  IIGS  screen  is 
associated  with  a  GrafPort  record,  which  specifies 
the  window's  drawing  environment.  Same  as  port, 
graphic  port. 

drawing  mask:  An  8-bit  by  8-bit  pattern  that 
controls  which  pixels  in  the  QuickDraw  pen  will 
be  modified  when  the  pen  draws. 

drawing  mode:  One  of  eight  possible  interactions 
between  pixels  in  QuickDraw  II 's  pen  pattern  and 
pixels  already  on  the  screen  that  fall  under  the 
pen's  path.  In  COPY  mode,  for  example,  pixels 
already  on  the  screen  are  ignored.  In  XOR  mode, 
on  the  other  hand,  bits  in  pixels  on  the  screen 
are  XOR'd  with  bits  in  pixels  in  the  pen;  the 
resulting  pixels  are  drawn  on  the  screen. 

drawing  pen:  See  pen. 

D  register:  See  direct  register. 

driver:  See  device  driver. 

dynamic  segment:  A  load  segment  capable  of 
being  loaded  during  program  execution. 
Compare  static  segment. 

edit  record:  A  complete  text  editing  environment 
in  the  Line  Edit  Tool  Set,  which  includes  the  text 
to  be  edited,  the  GrafPort  and  rectangle  in  which 
to  display  the  text,  the  arrangement  of  the  text 
within  the  rectangle,  and  other  editing  and 
display  information. 

e  flag:  One  of  three  flag  bits  in  the  65816 
processor  that  programs  use  to  control  the 
processor's  operating  modes.  The  setting  of  the  e 
flag  determines  whether  the  processor  is  in 
native  mode  (6502),  or  emulation  mode  (65816). 
See  also  m  flag  and  x  flag. 

emulate:  To  operate  in  a  way  identical  to  a 
different  system.  For  example,  the  65816 
microprocessor  in  the  Apple  IIGS  can  carry  out 
all  the  instructions  in  a  program  originally 
written  for  an  Apple  II  that  uses  a  6502 
microprocessor,  thus  emulating  the  6502. 
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emulation  mode:  The  8-bit  configuration  of  the 
65816  processor  in  which  it  functions  like  a  6502 
processor  in  all  respects  except  clock  speed. 

enable:  To  make  responsive  to  user  manipulation. 
A  dialog  or  menu  that  is  enabled  can  be  selected 
by  the  user.  Enabling  does  not  affect  how  an  item 
is  displayed.  Compare  activate. 

end-of-file:  See  EOF. 

EOF:  The  logical  size  of  a  ProDOS  16  file;  it  is  the 
number  of  bytes  that  may  be  read  from  or 
written  to  the  file. 

erase:  In  QuickDraw  II,  to  color  an  area  with  the 
background  pattern. 

error:  The  state  of  a  computer  after  it  has 
detected  a  fault  in  one  or  more  commands  sent 
to  it.  Also  called  error  condition. 

error  message:  A  message  issued  by  the  system  or 
application  program  when  it  has  encountered  an 
abnormal  situation  or  an  error  in  data. 

event:  A  notification  to  an  application  of  some 
occurrence  (such  as  an  interrupt  generated  by  a 
keypress)  to  which  the  application  may  want  to 
respond. 

event  code:  A  numeric  value  assigned  to  each 
event  by  the  Event  Manager.  Compare  task  code. 

event-driven:  A  kind  of  program  that  responds  to 
user  inputs  in  real  time  by  repeatedly  testing  for 
events.  An  event-driven  program  does  nothing 
until  it  detects  an  event  such  as  a  click  of  the 
mouse  button. 

Event  Manager:  An  Apple  IIGS  tool  set  that 
detects  events  as  they  happen,  and  passes  the 
events  on  to  the  application  or  to  the 
appropriate  event  handler,  such  as  TaskMaster. 

event  mask:  A  parameter  passed  to  an  Event 
Manager  routine  to  specify  which  types  of  events 
the  routine  should  apply  to. 

event  queue:  A  list  of  pending  events  maintained 
by  the  Event  Manager. 


event  record:  The  internal  representation  of  an 
event,  through  which  your  program  learns  all 
pertinent  information  about  that  event. 

execution  mode:  One  of  two  general  states  of 
execution  of  the  65816  processor — native  mode 
and  6502  emulation  mode. 

extended  task  event  record:  A  data  structure 
based  on  the  event  record  that  contains 
information  used  and  returned  by  TaskMaster. 

FALSE:  Zero.  The  result  of  a  Boolean  operation. 
Opposite  of  TRUE. 

file:  Any  named,  ordered  collection  of 
information  stored  on  a  disk.  Application 
programs  and  operating  systems  on  disks  are 
examples  of  files;  so  also  are  text  or  graphics 
created  by  applications  and  saved  on  disks.  Text 
and  graphics  files  are  also  called  documents. 

file  level:  See  system  file  leveL 

file  mark:  See  Mark. 

filename:  The  string  of  characters  that  identifies  a 
particular  file  within  its  directory.  ProDOS 
filenames  may  be  up  to  15  characters  long. 
Compare  pathname. 

file  type:  An  attribute  of  a  ProDOS  file  that 
characterizes  its  contents  and  indicates  how  the 
file  may  be  used.  On  disk,  file  types  are  stored  as 
numbers;  in  a  directory  listing,  they  are  often 
displayed  as  three-character  or  single-word 
mnemonic  codes. 

fill  mode:  A  display  option  in  Super  Hi-Res  320 
mode.  In  fill  mode,  pixels  in  memory  with  the 
value  0  are  automatically  assigned  the  color  of 
the  previous  nonzero  pixel  on  the  scan  line;  the 
program  thus  need  assign  explicit  pixel  values 
only  to  change  pixel  colors. 
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firmware:  Programs  stored  permanently  in  ROM; 
most  provide  an  interface  to  system  hardware. 
Such  programs  (for  example,  the  Monitor 
program)  are  built  into  the  computer  at  the 
factory.  They  can  be  executed  at  any  time  but 
cannot  be  modified  or  erased.  Compare 
hardware  and  software 

fixed:  Not  movable  in  memory  once  allocated. 
Also  called  immovable.  Program  segments  that 
must  not  be  moved  are  placed  in  fixed  memory 
blocks.  Opposite  of  movable. 

fixed-address:  A  memory  block  that  must  be  at  a 
specified  address  when  allocated. 

fixed-bank:  A  block  of  memory  that  must  start  in 
a  specified  bank. 

flag:  A  variable  whose  value  (usually  1  or  0, 
standing  for  true  or  false)  indicates  whether  some 
condition  holds  or  whether  some  event  has 
occurred.  A  flag  is  used  to  control  the  program's 
actions  at  some  later  time. 

folder:  See  subdirectory. 

font:  In  typography,  a  complete  set  of  type  in  one 
size  and  style  of  character.  In  computer  usage,  a 
collection  of  letters,  numbers,  punctuation  marks, 
and  other  typographical  symbols  with  a 
consistent  appearance;  the  size  and  style  can  be 
changed  readily.  See  also  font  scaling. 

font  family:  All  fonts  that  share  the  same  name 
but  may  vary  in  size  or  style.  For  example,  all 
fonts  named  Helvetica  are  in  the  same  family, 
even  though  that  family  contains  Helvetica, 
Helvetica  Narrow  and  Helvetica  Bold. 

font  height:  The  vertical  distance  from  a  font's 
ascent  line  to  its  descent  line. 

font  ID:  A  number  that  specifies  a  font  by  family, 
style,  and  size. 

font  scaling:  A  process  by  which  the  Font 
Manager  creates  a  font  at  one  size  by  enlarging 
or  reducing  characters  in  an  existing  font  of 
another  size. 


font  strike:  A  1  bit/pixel  pixelmap  consisting  of 
the  character  images  of  every  defined  character 
in  the  font,  placed  sequentially  in  order  of 
increasing  ASCII  code. 

foreground  color:  The  color  of  the  foreground 
pixels  in  text;  by  default  it  is  white. 

foreground  pixels:  In  a  character  image,  the 

pixels  corresponding  to  the  character  itself. 

frame  region:  The  part  of  a  window  that 
surrounds  the  window's  content  region  and 

contains  standard  window  controls. 

full  pathname:  The  complete  name  by  which  a 
file  is  specified,  starting  with  the  volume 
directory  name.  A  full  pathname  always  begins 
with  a  slash  (J),  because  a  volume  directory 
name  always  begins  with  a  slash.  See  also 
pathname. 

Function  Pointer  Table  (FPT):  A  table, 
maintained  by  the  Tool  Locator,  that  points  to  all 
routines  in  a  given  tool  set. 

general  logic  unit:  See  GLU. 

GetNextEvent:  The  Event  Manager  call  that  an 
application  can  make  on  each  cycle  through  its 
main  event  loop.  Compare  TaskMaster. 

global  coordinates:  The  coordinate  system 
assigned  to  a  pixel  image  (such  as  screen 
memory)  to  which  QuickDraw  II  draws.  In  global 
coordinates,  the  origin  (upper-left  corner)  of  the 
pixel  image's  boundary  rectangle  has  the  value 
(0,0).  Compare  local  coordinates. 

global  symbol:  A  label  in  a  segment  that  may  be 
referenced  by  other  segments.  Compare  with 
local  symbol,  private  symbol. 

GLU:  Abbreviation  of  general  logic  unit,  a  class  of 
custom  integrated  circuits  used  as  interfaces 
between  different  parts  of  the  computer. 

go-away  area:  A  subregion  in  a  window  frame, 
corresponding  to  the  close  box.  Clicking  inside 
this  region  of  the  active  window  makes  the 
window  close  or  disappear. 
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GrafPort:  A  data  structure  (record)  that  specifies 
a  complete  drawing  environment,  including  such 
elements  as  a  pixel  image,  boundaries  within 
which  to  draw,  a  character  font,  patterns  for 
drawing  and  erasing,  and  other  pen 
characteristics. 

graphic  Interface:  An  interface  between  computer 
and  user  in  which  all  screen  drawing  or  other 
output,  including  text,  is  done  by  graphic 
routines.  Desktop  programs  use  a  graphic 
interface.  Compare  text-based  interface. 

graphic  port:  A  specification  for  how  and  where 
QuickDraw  II  draws.  A  graphic  port  is  defined  by 
its  GrafPort  record;  an  application  may  have 
more  that  one  graphic  port  open  at  one  time, 
each  defined  by  its  own  GrafPort.  Same  as 
drawing  environment 

grow  area:  A  window-frame  subregion  in  which 
dragging  changes  the  size  of  the  window. 

handle:  See  memory  handle. 

hardware:  In  computer  terminology,  the 
machinery  that  makes  up  a  computer  system. 
Compare  firmware,  software. 

Heartbeat  Interrupt  Task  queue  A  list  of  tasks, 
such  as  cursor-movement  updating  or  checking 
stack  size,  to  be  performed  during  vertical 
blanking.  Heartbeat  tasks  are  manipulated  by  the 
Miscellaneous  Tool  Set. 

Heartbeat  routines:  Routines  that  execute  at  some 
multiple  of  the  heartbeat  interrupt  signal,  which 
occurs  during  the  vertical  blanking  interval 
(every  Vfio  of  a  second). 

hex:  See  hexadecimal. 

hexadecimal:  The  representation  of  numbers  in 
the  base-16  system,  using  the  ten  digits  0  through 
9  and  the  six  letters  A  through  F.  Each 
hexadecimal  digit  corresponds  to  a  sequence  of 
four  binary  digits  (bits).  Hexadecimal  numbers 
are  usually  preceded  by  a  dollar  sign  ($). 


hide:  To  make  invisible  (but  not  necessarily  to 
discard)  an  object  on  the  screen  such  as  a 
window. 

highlight:  To  make  something  visually  distinct. 
For  example,  when  a  button  on  a, dialog  box  is 
selected,  it  appears  as  light  letters  on  a  dark 
background,  rather  than  dark-on-light.  An  active 
window  or  control  is  highlighted  differently  than 
an  inactive  one. 

HodgePodge:  A  sample  Apple  IIGS  desktop 
application;  the  program  described  in  this  book. 

horizontal  blanking:  The  interval  between  the 
drawing  of  each  scan  line  on  a  video  display. 

Human  Interface  Guidelines:  Apple  Computer's 
set  of  conventions  and  suggestions  for  writing 
desktop  programs.  Programs  that  follow  the 
Human  Interface  Guidelines  present  a  consistent 
and  friendly  interface  to  users. 

IC:  See  integrated  circuit. 

icon:  An  image  that  graphically  represents  an 
object,  a  concept,  or  a  message. 

i  flag:  A  bit  in  the  65816  microprocessor's 
Processor  Status  register  that,  if  set  to  1,  disables 
interrupts. 

image:  A  representation  of  the  contents  of 
memory.  A  code  image  consists  of  machine- 
language  instructions  or  data  that  may  be  loaded 
unchanged  into  memory.  See  also  pixel  image. 

inactive:  Controls  that  have  no  meaning  or  effect 
in  the  current  context,  such  as  an  Open  button 
when  no  document  has  been  selected  to  be 
opened.  These  inactive  controls  are  not  affected 
by  the  user's  mouse  actions  and  are  dimmed  on 
the  screen.  Compare  disable. 

index  register:  A  register  in  a  computer  processor 
that  holds  an  index  for  use  in  indexed 
addressing.  The  6502  and  65816  microprocessors 
used  in  the  Apple  II  family  of  computers  have 
two  index  registers,  called  the  X  register  and  the 
Y  register. 
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information  bar:  An  optional  component  of  a 
window.  If  present,  the  information  bar  appears 
just  below  the  title  bar.  It  may  contain  any 
information  the  application  that  created  the 
window  wishes. 

initialization  file:  A  program  (in  the 
SYSTEM .  SETUP  subdirectory  of  the  boot  disk) 
that  is  loaded  and  executed  at  system  startup, 
independently  of  any  application. 

initialization  segment:  A  segment  in  an  initial 
load  file  that  is  loaded  and  executed 
independently  of  the  rest  of  the  program.  It  is 
commonly  executed  first,  to  perform  any 
initialization  that  the  program  may  require. 

input/output:  See  I/O. 

insertion  point:  The  place  in  a  document  where 
something  will  be  added;  it  is  selected  by  clicking 
and  is  normally  represented  by  a  blinking 
vertical  bar. 

instrument:  A  data  structure,  used  by  the  Note 
Sequencer  and  Synthesizer,  that  specifies  such 
parameters  as  the  amplitude  envelope,  pitchbend 
and  vibrato  characteristics,  and  the  specific 
waveforms  that  characterize  the  sound  to  be 
played. 

integer:  A  whole  number  in  fixed-point  form. 

Integer  Math  Tool  Set:  The  Apple  IIGS  tool  set 
that  performs  simple  mathematical  functions  on 
integers  and  other  fixed-point  numbers  and 
converts  numbers  to  their  ASCII  string 
equivalents. 

integrated  circuit:  An  electronic 
circuit — including  components  and 
interconnections — entirely  contained  in  a  single 
piece  of  semiconducting  material,  usually  silicon. 
Often  referred  to  as  a  chip. 

interface:  (1)  The  general  form  of  interaction 
between  a  user  and  a  computer.  (2)  In 
programming,  the  compile-time  and  runtime 
linkage  between  your  program  and  toolbox 
routines. 


interface  library:  A  set  or  vanaDie  aeiimuuna  <mu 
data-structure  definitions  that  link  a  program 
(such  as  a  C  application)  with  software  written  in 
another  language  (such  as  the  Apple  IIGS 
Toolbox). 

interrupt:  A  temporary  suspension  in  the 
execution  of  a  main  program  that  allows  the 
computer  to  perform  some  other  task,  typically 
in  response  to  a  signal  from  a  peripheral  device 
or  other  source  external  to  the  computer. 

interrupt  environment:  The  machine  state, 
including  register  length  and  contents,  within 
which  the  interrupt  handler  executes. 

invert:  To  highlight  by  changing  white  pixels  to 
black  and  vice  versa. 

I/O:  Input/Output.  A  general  term  that 
encompasses  input/output  activity,  the  devices 
that  accomplish  it,  and  the  data  involved. 

I/O  space:  The  portion  of  the  memory  map  in  a 
standard  Apple  II  (and  in  banks  $00,  $01,  $E0, 
and  $E1  of  an  Apple  IIGS)  with  addresses 
between  $C000  and  $CFFF.  Programs  perform 
I/O  by  writing  to  or  reading  from  locations  in 
this  I/O  space. 

item:  A  component  of  a  dialog  box,  such  as  a 
button,  text  field,  or  icon. 

item  ID:  A  unique  number  that  defines  an  item  in 
a  dialog  box  and  allows  further  reference  to  it. 

item  line:  The  line  of  text  that  defines  a  menu 
item's  name  and  appearance. 

item  list:  A  list  of  information  about  all  the  items 
in  a  dialog  or  alert  box. 

item  type:  Identifies  the  type  of  dialog  item, 
usually  represented  by  a  predefined  constant 
(such  as  editLine)  or  a  series  of  constants 
(such  as  editLine+itemDisable). 

Job  dialog  box:  A  dialog  box  presented  when  the 
user  selects  Print  from  the  File  menu. 
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joystick:  A  peripheral  device  with  a  lever, 
typically  used  to  move  creatures  and  objects  in 
game  programs;  a  joystick  can  also  be  used  in 
applications  such  as  computer-aided  design  and 
graphics  programs. 

JSL:  Jump  to  Subroutine  (Long),  a  65816  assembly- 
language  instruction  that  requires  a  long  (3-byte) 
address.  JSL  can  be  used  to  transfer  execution  to 
code  in  another  memory  bank. 

JSR:  Jump  to  Subroutine,  a  6502  and  65816 
assembly-language  instruction  that  requires  a  2- 
byte  address. 

Jump  Table:  A  table  constructed  in  memory  by 
the  System  Loader.  The  Jump  Table  contains  all 
references  to  dynamic  segments  that  may  be 
called  during  execution  of  the  program. 

K:  See  kilobyte. 

keyboard  equivalent:  The  combination  of  the 
Apple  key  and  another  key,  used  to  invoke  a 
menu  item  from  the  keyboard. 

key-down:  An  event  type  caused  by  the  user's 
pressing  any  character  key  on  the  keyboard  or 
keypad.  The  character  keys  include  all  keys  except 
Shift,  Caps  Lock,  Control,  Option,  and  Apple, 
which  are  called  modifier  keys.  Modifier  keys  are 
treated  differently  and  generate  no  keyboard 
events  of  their  own. 

kilobyte  (K):  A  unit  of  measurement  consisting  of 
1024  (210)  bytes.  In  this  usage,  kilo  (from  the 
Greek,  meaning  a  thousand)  stands  for  1024. 
Thus,  64K  memory  equals  65,536  bytes.  See  also 
megabyte. 

kind-  See  segment  kind. 


language  card:  Memory  with  addresses  between 
$D000  and  $FFFF  in  any  Apple  II-family 
computer.  It  includes  two  RAM  banks  in  the 
$Dxxx  space,  called  bank-switched  memory.  The 
language  card  was  originally  a  peripheral  card 
for  the  48K  Apple  II  or  Apple  II  Plus  that 
expanded  the  computer's  memory  capacity  to 
64K  and  provided  space  for  an  additional  dialect 
of  BASIC. 

leading:  (Pronounced  LED-ing.)  The  space 
between  lines  of  text.  It  is  the  number  of  pixels 
vertically  between  the  descent  line  of  one 
character  and  the  ascent  line  of  the  character 
immediately  beneath  it. 

length  byte:  The  first  byte  of  a  Pascal  string.  It 

specifies  the  length  of  the  string,  in  bytes. 

library  (or  library  file):  An  object  file  containing 
program  segments,  each  of  which  can  be  used  in 
any  number  of  programs.  The  linker  can  search 
through  the  library  file  for  segments  that  have 
been  referenced  in  the  program  source  file. 

library  dictionary  segment:  The  first  segment  of  a 
library  file;  it  contains  a  list  of  all  the  symbols  in 
the  file  together  with  their  locations  in  the  file. 
The  linker  uses  the  library  dictionary  segment  to 
find  the  segments  it  needs. 

line:  In  QuickDraw  II,  the  straight-line  trajectory 
between  two  points  on  the  coordinate  plane.  The 
line  is  specified  by  its  starting  and  ending  points. 

LineEdit  Tool  Set:  The  Apple  IIGS  tool  set  that 
provides  simple  text-editing  functions.  It  is  used 
mostly  in  dialog  boxes. 

line  height:  The  total  amount  of  vertical  space 
from  line  to  line  in  a  text  document.  Line  height 
is  the  sum  of  ascent,  descent,  and  leading. 

LinkEd:  A  command  language  that  can  be  used  to 
control  the  APW  Linker. 

linker:  A  program  that  combines  files  generated 
by  compilers  and  assemblers,  resolves  all 
symbolic  references,  and  generates  a  file  that  can 
be  loaded  into  memory  and  executed. 
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Lisa:  A  model  of  Apple  computer;  the  first 
computer  that  offered  windows  and  the  use  of  a 
mouse  to  choose  commands.  The  Lisa  is  now 
known  as  the  Macintosh  XL.' 

list:  See  list  controL 

list  control:  A  custom  control  created  by  the  List 
Manager.  It  is  a  scrollable,  vertical  arrangement 
of  similar  items  on  the  screen;  the  items  are 
selectable  by  the  user. 

List  Manager:  The  Apple  IIGS  tool  set  that  allows 
an  application  to  present  the  user  with  a  list  from 
which  to  choose.  For  example,  the  Font  Manager 
uses  the  List  Manager  to  arrange  lists  of  fonts. 

load:  To  transfer  information  from  a  peripheral 
storage  medium  (such  as  a  disk)  into  main 
memory  for  use — for  example,  to  transfer  a 
program  into  memory  for  execution. 

load  file:  The  output  of  the  linker.  Load  files 
contain  memory  images  that  the  system  loader 
can  load  into  memory,  together  with  relocation 
dictionaries  that  the  loader  uses  to  relocate 
references. 

load  segment:  A  segment  in  a  load  file.  Any 
number  of  object  segments  can  go  into  the  same 
load  segment. 

local  coordinates:  A  coordinate  system  unique  to 
each  GrafPort  and  independent  of  the  global 
coordinates  of  the  pixel  image  that  the  port  is 
associated  with.  For  example,  local  coordinates 
do  not  change  as  a  window  is  dragged  across  the 
screen;  global  coordinates  do  not  change  as  a 
window's  contents  are  scrolled. 

local  symbol:  A  label  defined  only  within  an 
individual  segment.  Other  segments  cannot 
reference  the  label.  Compare  with  global  symboL 

Loclnfo:  Acronym  for  location  information.  The 
data  structure  (record)  that  ties  the  coordinate 
plane  to  an  individual  pixel  image  in  memory. 


lock:  To  prevent  a  memory  block  from  being 
moved  or  purged.  A  block  may  be  locked  or 
unlocked  by  a  call  to  the  Memory  Manager. 

long  (or  long  word):  On  the  Apple  IIGS,  a  32-bit 
(4-byte)  data  type. 

Macintosh:  A  family  of  Apple  computers;  for 
example,  the  Macintosh  512K  and  the  Macintosh 
Plus.  Macintosh  computers  have  high-resolution 
screens  and  use  mouse  devices  for  choosing 
commands  and  for  drawing  pictures. 

macro:  A  single  keystroke  or  command  that  a 
program  replaces  with  several  keystrokes  or 
commands.  For  example,  the  AP W  Editor  allows 
you  to  define  macros  that  execute  several  editor 
keystroke  commands;  the  APW  Assembler  allows 
you  to  define  macros  that  execute  instructions 
and  directives.  Macros  are  almost  like  higher- 
level  language  instructions,  making  assembly- 
language  programs  easier  to  write  and  complex 
keystrokes  easier  to  execute. 

macro  library:  A  file  of  related  macros. 

main  event  loop:  The  central  routine  of  an  event- 
driven  program.  During  execution,  the  program 
continually  cycles  through  the  main  event  loop, 
branching  off  to  handle  events  as  they  occur  and 
then  returning  to  the  event  loop. 

mainID:  A  subfield  of  the  User  ID.  Each  running 
program  is  assigned  a  unique  mainID. 

manager:  See  tool  set 

Mark:  The  current  position  in  an  open  file.  It  is 
the  point  in  the  file  at  which  the  next  read  or 
write  operation  will  occur. 

mask:  (n)  A  parameter,  typically  one  or  more 
bytes  long,  whose  individual  bits  are  used  to 
permit  or  block  particular  features.  See,  for 
example,  event  mask  (v)  To  apply  a  mask. 

master  color  value:  A  2-byte  number  that 
specifies  the  relative  intensities  of  the  red,  green, 
and  blue  signals  output  by  the  Apple  IIGS  video 
hardware. 
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Lisa:  A  model  of  Apple  computer;  the  first 
computer  that  offered  windows  and  the  use  of  a 
mouse  to  choose  commands.  The  Lisa  is  now 
known  as  the  Macintosh  XL.' 

list:  See  list  controL 

list  control:  A  custom  control  created  by  the  List 
Manager.  It  is  a  scrollable,  vertical  arrangement 
of  similar  items  on  the  screen;  the  items  are 
selectable  by  the  user. 

List  Manager:  The  Apple  IIGS  tool  set  that  allows 
an  application  to  present  the  user  with  a  list  from 
which  to  choose.  For  example,  the  Font  Manager 
uses  the  List  Manager  to  arrange  lists  of  fonts. 

load:  To  transfer  information  from  a  peripheral 
storage  medium  (such  as  a  disk)  into  main 
memory  for  use — for  example,  to  transfer  a 
program  into  memory  for  execution. 

load  file:  The  output  of  the  linker.  Load  files 
contain  memory  images  that  the  system  loader 
can  load  into  memory,  together  with  relocation 
dictionaries  that  the  loader  uses  to  relocate 
references. 

load  segment:  A  segment  in  a  load  file.  Any 
number  of  object  segments  can  go  into  the  same 
load  segment. 

local  coordinates:  A  coordinate  system  unique  to 
each  GrafPort  and  independent  of  the  global 
coordinates  of  the  pixel  image  that  the  port  is 
associated  with.  For  example,  local  coordinates 
do  not  change  as  a  window  is  dragged  across  the 
screen;  global  coordinates  do  not  change  as  a 
window's  contents  are  scrolled. 

local  symbol:  A  label  defined  only  within  an 
individual  segment.  Other  segments  cannot 
reference  the  label.  Compare  with  global  symboL 

Loclnfo:  Acronym  for  location  information.  The 
data  structure  (record)  that  ties  the  coordinate 
plane  to  an  individual  pixel  image  in  memory. 


lock:  To  prevent  a  memory  block  from  being 
moved  or  purged.  A  block  may  be  locked  or 
unlocked  by  a  call  to  the  Memory  Manager. 

long  (or  long  word):  On  the  Apple  IIGS,  a  32-bit 
(4-byte)  data  type. 

Macintosh:  A  family  of  Apple  computers;  for 
example,  the  Macintosh  512K  and  the  Macintosh 
Plus.  Macintosh  computers  have  high-resolution 
screens  and  use  mouse  devices  for  choosing 
commands  and  for  drawing  pictures. 

macro:  A  single  keystroke  or  command  that  a 
program  replaces  with  several  keystrokes  or 
commands.  For  example,  the  AP W  Editor  allows 
you  to  define  macros  that  execute  several  editor 
keystroke  commands;  the  APW  Assembler  allows 
you  to  define  macros  that  execute  instructions 
and  directives.  Macros  are  almost  like  higher- 
level  language  instructions,  making  assembly- 
language  programs  easier  to  write  and  complex 
keystrokes  easier  to  execute. 

macro  library:  A  file  of  related  macros. 

main  event  loop:  The  central  routine  of  an  event- 
driven  program.  During  execution,  the  program 
continually  cycles  through  the  main  event  loop, 
branching  off  to  handle  events  as  they  occur  and 
then  returning  to  the  event  loop. 

mainID:  A  subfield  of  the  User  ID.  Each  running 
program  is  assigned  a  unique  mainID. 

manager:  See  tool  set 

Mark:  The  current  position  in  an  open  file.  It  is 
the  point  in  the  file  at  which  the  next  read  or 
write  operation  will  occur. 

mask:  (n)  A  parameter,  typically  one  or  more 
bytes  long,  whose  individual  bits  are  used  to 
permit  or  block  particular  features.  See,  for 
example,  event  mask  (v)  To  apply  a  mask. 

master  color  value:  A  2-byte  number  that 
specifies  the  relative  intensities  of  the  red,  green, 
and  blue  signals  output  by  the  Apple  IIGS  video 
hardware. 
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master  User  ID:  The  value  of  a  User  ID, 
disregarding  the  contents  of  the  auxID  field.  If  an 
application  allocates  various  memory  blocks  and 
assigns  them  unique  ID's  consisting  of  different 
auxID  values  added  to  its  own  User  ID,  then  all 
will  share  the  same  Master  User  ID  and  all  can  be 
purged  or  disposed  with  a  single  call. 

Mb:  See  megabyte. 

megabyte  (Mb):  A  unit  of  computer  memory  or 
disk  drive  capacity  that  equals  1,048,576  bytes. 

megahertz  (MHz):  A  unit  of  measurement  of 
frequency,  equal  to  1,000,000  hertz  (cycles  per 
second);  abbreviated  MHz. 


memory  block:  See  block  (2). 

memory  expansion  card:  A  memory  card  that 
increases  Apple  IIGS  internal  memory  capacity 
beyond  256K,  up  to  8  megabytes 

memory  fragmentation:  A  condition  in  which 
free  (unallocated)  portions  of  memory  are 
scattered  because  of  repeated  allocation  and 
deallocation  of  blocks  by  the  Memory  Manager. 

memory  handle:  A  number  that  identifies  a 
memory  block.  A  handle  is  a  pointer  to  a 
pointer— it  is  the  address  of  a  master  pointer, 
which  in  turn  contains  the  address  of  the  block. 

memory  image  See  image. 

Memory  Manager:  The  Apple  IIGS  tool  set  that 
manages  memory  use.  The  Memory  Manager 
keeps  track  of  how  much  memory  is  available, 
and  allocates  memory  blocks  to  hold  program 
segments  or  data. 

Memory  Segment  Table:  A  linked  list  in  memory, 
created  by  the  loader,  that  allows  the  loader  to 
keep  track  of  the  segments  that  have  been  loaded 
into  memory. 

menu:  A  list  of  choices  presented  by  a  program, 
from  which  the  user  can  select  an  action.  See  also 
pull-down  menu. 


menu  bar:  The  horizontal  strip  at  the  top  of  the 
screen  that  contains  menu  titles  for  the  pull-down 
menus. 

menu  ID:  A  number  in  the  menu  record  that 
identifies  an  individual  menu. 

menu  line:  A  line  of  text  plus  code  characters 
that  defines  the  appearance  of  a  particular  menu 
title. 

Menu  Manager:  The  Apple  IIGS  tool  set  that 
maintains  the  pull-down  menus  and  the  items  in 
the  menus. 

m  flag:  One  of  3  flags  in  the  65816 
microprocessor's  Processor  Status  register  that 
controls  execution  mode.  When  the  m  flag  is  set 
to  1,  the  accumulator  is  8  bits  wide;  otherwise,  it  is 
16  bits  wide. 

MHz:  See  megahertz. 

microprocessor:  A  central  processing  unit  that  is 
contained  in  a  single  integrated  circuit.  The 
Apple  IIGS  uses  a  65816  microprocessor. 

minipalette:  In  Super  Hi-Res  640  mode,  a  quarter 
of  the  color  table.  Each  pixel  in  640  mode  can 
have  one  of  four  colors  specified  in  a 
minipalette. 

Miscellaneous  Tool  Set:  The  Apple  IIGS  tool  set 
that  includes  mostly  system-level  routines  that 
must  be  available  for  other  tool  sets. 

missing  symbol:  In  a  font,  the  symbol  substituted 
for  any  ASCII  value  for  which  the  font  does  not 
have  a  defined  symbol.  In  the  Apple  IIGS  system 
font,  the  missing  symbol  is  a  box  containing  a 
question  mark. 

modal  dialog  box:  A  dialog  box  that  puts  the 
machine  in  a  state  such  that  the  user  cannot 
execute  functions  outside  of  the  dialog  box,  until 
the  dialog  box  is  closed. 

mode:  A  state  of  a  computer  or  system  that 
determines  its  behavior.  A  manner  of  operating. 
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modeless  dialog  box:  A  dialog  box  that  lets  the 
user  take  other  action  besides  responding  to  the 
dialog  box.  Compare  modal  dialog  box. 

modification  date:  An  attribute  of  a  ProDOS  file; 
it  specifies  the  date  on  which  the  content  of  the 
file  was  last  changed. 

modification  time:  An  attribute  of  a  ProDOS  file; 
it  specifies  the  time  at  which  the  content  of  the 
file  was  last  changed. 

Monitor  program:  A  firmware  program  built  into 
the  ROM  of  Apple  II  computers,  used  for  directly 
inspecting  or  changing  the  contents  of  main 
memory  and  for  operating  the  computer  at  the 
machine-language  level. 

monospaced:  Said  of  a  font  whose  character 
widths  are  all  identical.  Compare  proportionally 
spaced. 

MOS:  Abbreviation  for  metal-oxide 
semiconductor,  a  method  of  fabricating 
integrated-circuits  on  silicon  by  using  layers  of 
silicon  dioxide  in  the  make-up  of  the  devices. 
Compare  CMOS. 

mouse:  A  small  device  that  the  user  moves 
around  on  a  flat  surface  next  to  the  computer. 
The  mouse  controls  a  pointer  on  the  screen 
whose  movements  correspond  to  those  of  the 
mouse.  The  pointer  selects  operations,  moves 
data,  and  draws  graphic  objects. 

mouse  button:  A  button  on  a  mouse  device  with 
which  the  user  selects  objects  on  the  screen. 

mouse-down:  An  action  or  an  event,  signifying 
that  the  user  has  pressed  the  mouse  button. 

mouse-up:  An  action  or  an  event,  signifying  that 
the  user  has  released  the  mouse  button. 

movable:  Able  to  be  moved  to  different  memory 
locations  during  program  execution  (a  memory 
block  attribute). 

native  mode:  The  l6-bit  operating  configuration 
of  the  65816  microprocessor. 


NDA:  See  new  desk  accessory. 

new  desk  accessory  (NDA):  A  desk  accessory 
designed  to  execute  in  a  desktop,  event-driven 
environment.  Compare  classic  desk  accessory. 

newline  read  mode:  A  file-reading  mode  in  which 
each  character  read  from  the  file  is  compared  to 
a  specified  character  (called  the  newline 
character);  if  there  is  a  match,  the  read  is 
terminated.  Newline  mode  is  typically  used  to 
read  individual  lines  of  text,  with  the  newline 
character  defined  as  a  carriage  return. 

NewWindow  parameter  list:  A  template 
describing  the  features  of  a  window  that  is  to  be 
created.  A  pointer  to  a  NewWindow  parameter 
list  is  a  required  input  to  the  NewWindow  call. 

NIL:  Pointing  to  a  value  of  0.  A  memory  handle  is 
NIL  if  the  address  it  points  to  is  filled  with  zeros. 
Handles  to  purged  memory  blocks  are  NIL. 
Compare  nulL 

Note  Sequencer:  The  Apple  IIGS  tool  set  that 
makes  it  possible  to  play  music  asynchronously 
in  programs. 

Note  Synthesizer:  An  Apple  IIGS  tool  set  that 
facilitates  creation  and  manipulation  of  musical 
notes. 

null:  Zero.  A  pointer  is  null  if  its  value  is  all  zeros. 
Compare  NIL. 

null  event:  An  event  reported  when  there  are  no 
other  events  to  report. 

null  prefix:  A  prefix  of  zero  length  (and  therefore 
nonexistent). 

object  file:  The  output  from  an  assembler  or 
compiler,  and  the  input  to  a  linker.  It  contains 
machine-language  instructions  as  well  as  other 
information.  Also  called  object  program  or 
object  code.  In  APW  an  object  file  cannot  be 
loaded  into  memory.  Compare  source  file,  load 
file. 
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object  module  format  (OMF):  The  file  format 
used  in  Apple  IIGS  object  files,  library  files,  and 
load  files. 

object  segment:  A  segment  in  an  object  file. 

offset:  The  number  of  character  positions  or 
memory  locations  away  from  a  point  of 
reference. 

OK:  One  of  two  predefined  item  ID  numbers  for 
dialog  box  buttons  (OK  =  1).  Compare  Cancel. 

OMF:  See  object  module  format 

operating  environment:  The  overall  hardware 
and  software  setting  within  which  a  program  runs. 
Also  called  execution  environment. 

operating  system:  A  general-purpose  program 
that  organizes  the  actions  of  the  various  parts  of 
the  computer  and  its  peripheral  devices.  See  also 
disk  operating  system. 

origin:  (1)  The  first  memory  address  of  a 
program  or  of  a  portion  of  one.  The  first 
instruction  to  be  executed.  (2)  The  location  (0,0) 
on  the  QuickDraw  II  coordinate  plane,  in  either 
global  coordinates  or  local  coordinates.  (3)  The 
upper-left  corner  of  any  rectangle  (such  as  a 
boundary  rectangle  or  port  rectangle)  in 
QuickDraw  II.  (4)  See  character  origin. 

oscillator:  A  device  that  generates  a  vibration.  In 
the  Apple  IIGS  Digital  Oscillator  Chip,  an 
oscillator  is  an  address  generator  that  points  to 
the  next  data  byte  in  memory  that  represents 
part  of  a  particular  sound  wave. 

oval:  A  circle  or  ellipse,  one  of  the  fundamental 
classes  of  objects  drawn  by  QuickDraw  II. 

overlay:  One  of  a  set  of  program  segments  meant 
to  alternately  occupy  the  same  memory  space. 
Use  of  overlays  is  one  way  to  minimize  the 
amount  of  memory  a  program  needs. 

pack:  To  compress  data  into  a  smaller  space  to 
conserve  storage  space. 


page:  (1)  A  portion  of  memory  256  bytes  long 
and  beginning  at  an  address  that  is  an  even 
multiple  of  256.  Memory  blocks  whose  starting 
addresses  are  an  even  multiple  of  256  are  said  to 
be  page-aligned.  (2)  (usually  capitalized)  An  area 
of  main  memory  containing  text  or  graphic 
information  being  displayed  on  the  screen. 

page-aligned:  Starting  at  a  memory  address  that 
is  an  even  multiple  of  256  (a  memory  block 
attribute).  See  page  (1). 

palette:  The  full  set  of  colors  available  for  an 
individual  screen  pixel. 

parameter:  A  value  passed  to  or  from  a  function 
or  other  routine. 

parameter  RAM:  RAM  on  the  Apple  IIGS  clock 
chip.  A  battery  preserves  the  clock  settings  and 
the  RAM  contents  when  the  power  is  off.  Control 
Panel  settings  are  kept  in  battery  RAM. 

partial  pathname:  A  pathname  that  includes  the 
filename  of  the  desired  file  but  excludes  the 
volume  directory  name  (and  possibly  one  or 
more  of  the  subdirectories  in  the  path).  It  is  the 
part  of  a  pathname  following  a  prefix — a  prefix 
and  a  partial  pathname  together  constitute  a  full 
pathname.  A  partial  pathname  does  not  begin 
with  a  slash  because  it  has  no  volume  directory 
name. 

Pascal:  A  high-level  programming  language. 
Named  for  the  philosopher  and  mathematician 
Blaise  Pascal. 

Pascal  string:  An  ASCII  character  string  preceded 
by  a  single  byte  whose  numerical  value  is  the 
number  of  characters  in  the  string.  Compare  C 
string 

paste:  To  place  the  desk  scrap  (contents  of  the 
Clipboard — whatever  was  last  cut  or  copied)  at 
the  insertion  point. 
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patch:  To  replace  one  or  more  bytes  in  memory 
or  in  a  file  with  other  values.  The  address  to 
which  the  program  must  jump  to  execute  a 
subroutine  is  patched  into  memory  at  load  time, 
when  the  System  Loader  performs  relocation  on 
a  file. 

pathname:  A  name  that  specifies  a  file.  It  is  a 
sequence  of  one  or  more  filenames  separated  by 
slashes,  tracing  the  path  through  subdirectories 
that  a  program  must  follow  to  locate  the  file.  See 
full  pathname,  partial  pathname,  prefix. 

pathname  prefix:  See  prefix. 

Pathname  Table:  A  table  constructed  in  memory 
by  the  System  Loader.  The  Pathname  Table 
contains  cross-references  between  load  files 
referenced  by  number  (in  the  Jump  Table)  and 
by  pathname  (in  the  file  directory). 

pattern:  (1)  An  8-by-8  pixel  image,  used  to  define 
a  repeating  design  (such  as  stripes)  or  color.  (2) 
A  series  of  commands  to  the  Note  Synthesizer. 

PB  register:  See  program  bank  register. 

PC  register:  A  register  within  the  65816 
microprocessor  that  keeps  track  of  the  memory 
address  of  the  next  instruction  to  be  executed.  PC 
stands  for  program  counter. 

pen:  The  conceptual  tool  with  which  QuickDraw  II 
draws  shapes  and  characters.  Each  GrafPort  has 
its  own  pen. 

pen  location:  The  position  (on  the  coordinate 
plane)  at  which  the  next  character  or  line  will  be 
drawn. 

pen  pattern:  See  pattern  (1). 

peripheral  card:  A  hardware  device  placed  inside 
a  computer,  and  connected  to  one  of  the 
computer's  peripheral  expansion  slots. 
Peripheral  cards  perform  a  variety  of  functions, 
from  controlling  a  disk  drive  to  providing  a 
clock/calendar. 

peripheral  device:  See  device. 


phrase:  In  music  synthesis,  a  set  of  pointers  to 
patterns  that  make  it  easy  to  build  repetitive, 
complex  passages  out  of  simple  patterns. 

picture:  A  saved  sequence  of  QuickDraw  drawing 
commands  (and,  optionally,  picture  comments) 
that  you  can  play  back  later  with  a  single 
procedure  call;  also,  the  image  resulting  from 
these  commands. 

pixel:  Short  for  picture  element.  The  smallest  dot 
you  can  draw  on  the  screen.  Also  a  location  in 
video  memory  that  corresponds  to  a  point  on 
the  graphics  screen  when  the  viewing  window 
includes  that  location.  In  the  Super  Hi-Res 
display  on  the  Apple  IIGS,  each  pixel  is 
represented  by  either  two  or  four  bits.  See    lso 
pixel  image. . 

pixel  image:  A  graphics  image  picture  consisting 
of  a  rectangular  grid  of  pixels. 

plain-styled:  Said  of  a  font  or  character  that  is 
not  bold,  italicized,  underlined,  or  otherwise 
styled  apart  from  ordinary  text. 

plane:  The  front-to-back  position  of  a  window, 
compared  to  other  windows  on  the  desktop. 

point:  A  unit  of  measurement  for  type;  12  points 
equal  1  pica,  and  6  picas  equal  1  inch;  thus,  1 
point  equals  v72  inch. 

pointer:  (1)  An  item  of  information  consisting  of 
the  memory  address  of  some  other  item.  For 
example,  the  65816  stack  register  contains  a 
pointer  to  the  top  of  the  stack.  (2)  The  mouse 
pointer,  an  arrow-shaped  cursor  whose  screen 
location  is  controlled  by  mouse  movements. 

pointing  device:  Any  device,  such  as  a  mouse, 
graphics  tablet,  or  light  pen,  that  can  be  used  to 
specify  locations  on  the  computer  screen. 

polygon:  Any  sequence  of  connected  lines. 

port:  (1)  A  socket  on  the  back  panel  of  the 
computer  where  the  user  can  plug  in  a  cable  to 
connect  a  peripheral  device,  another  computer, 
or  a  network.  (2)  A  graphic  port  (GrafPort). 
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portRect:  The  GrafPort  field  that  defines  the 
port's  port  rectangle. 

port  rectangle:  A  rectangle  that  describes  the 
active  region  of  a  GrafPort's  pixel  map— the  part 
that  QuickDraw  II  can  draw  into.  The  content 
region  of  a  window  on  the  desktop  corresponds 
to  the  window's  port  rectangle. 

position-independent:  Said  of  code  that  can 
execute,  without  modification  of  any  kind,  at  any 
location  in  memory.  Compare  absolute, 
relocatable. 

post  To  place  an  event  in  the  event  queue  for 
later  processing. 

prefix:  A  pathname  starting  with  a  volume  name 
and  ending  with  a  subdirectory  name.  It  is  the 
part  of  a  full  pathname  that  precedes  a  partial 
pathname — a  prefix  and  a  partial  pathname 
together  constitute  a  full  pathname.  A  prefix 
always  starts  with  a  slash  CO  because  a  volume 
directory  name  always  starts  with  a  slash. 

prefix  number:  A  code  used  to  represent  a 
particular  prefix.  Under  ProDOS  16,  there  are 
nine  prefix  numbers,  each  consisting  of  a 
numeral  followed  by  a  slash:  0/,  1/ 8/,  and  •/. 

P  register:  See  status  register. 

printing  loop:  The  page-by-page  cycle  that  an 
application  goes  through  when  it  prints  a 
document. 

Print  Manager:  The  Apple  lies  tool  set  that  allows 
an  application  to  use  standard  QuickDraw  II 
routines  to  print  text  or  graphics  on  a  printer. 

print  record:  A  record  containing  all  the 
information  needed  by  the  Print  Manager  to 
perform  a  particular  printing  job. 

private  scrap:  A  buffer  (and  its  contents)  set  up 
by  an  application  for  cutting  and  pasting, 
analogous  to  but  apart  from  the  desk  scrap. 

private  symbol:  A  label  in  a  segment  that  may  be 
referenced  by  other  segments  in  the  same  file, 
but  not  by  segments  in  other  files. 


processor  status  register:  See  status  register. 

ProDOS:  A  family  of  disk  operating  systems 
developed  for  the  Apple  II  family  of  computers. 
ProDOS  stands  for  Professional  Disk  Operating 
System,  and  includes  both  ProDOS  8  and 
ProDOS  16. 

ProDOS  8:  A  disk  operating  system  developed  foi 
standard  Apple  II  computers.  It  runs  on  6502- 
series  microprocessors  and  on  the  Apple  IIGS 
when  the  65816  processor  is  in  6502  emulation 
mode. 

ProDOS  16:  A  disk  operating  system  developed 
for  65816  native-mode  operation  on  the  Apple 
IIGS.  It  is  functionally  similar  to  ProDOS  8  but 
more  powerful. 

program  bank  register:  The  65816  register  whose 
contents  form  the  high-order  byte  of  all  3-byte 
code  address  operands. 

program  counter:  See  PC  register. 

program  status  register:  See  status  register. 

proportionally  spaced:  Said  of  a  font  whose 
characters  vary  in  width,  so  the  amount  of 
horizontal  space  needed  for  each  character  is 
proportional  to  its  width.  Compare  monospaced. 

pull-down  menu:  A  set  of  choices  for  actions  that 
appears  near  the  top  of  the  display  screen  in  a 
desktop  application,  usually  overlaying  the 
present  contents  of  the  screen  without  disrupting 
them.  Dragging  through  the  menu  and  releasing 
the  mouse  button  while  a  command  is 
highlighted  chooses  [hat  command. 

purge:  To  temporarily  deallocate  a  memory 
block.  The  Memory  Manager  purges  a  block  by 
setting  its  master  pointer  to  NIL  (0).  All  handles 
to  the  pointer  are  still  valid,  so  the  block  can  be 
reconstructed  quickly.  Compare  dispose. 
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purge  leveL  A  memory  block  attribute,  indicating 
that  the  Memory  Manager  may  purge  the  block  if 
it  needs  additional  memory  space.  Purgeable 
blocks  have  different  purge  levels,  or  priorities 
for  purging;  these  levels  are  set  by  Memory 
Manager  calls. 

queue:  A  list  in  which  entries  are  added  at  one 
end  and  removed  at  the  other,  causing  entries  to 
be  removed  in  first-in,  first-out  (FIFO)  order. 
Compare  stack. 

QuickDraw  II:  The  Apple  IIGS  tool  set  that 
controls  the  graphics  environment  and  draws 
simple  objects  and  text.  Other  tools  call 
QuickDraw  II  to  draw  such  things  as  windows. 

QuickDraw  n  Auxiliary:  An  Apple  IIGS  tool  set 
that  provides  extensions  to  the  capabilities  of 
QuickDraw  n. 

quit:  To  terminate  execution  in  an  orderly 
manner.  Apple  IIGS  applications  quit  by  making  a 
ProDOS  16  QUIT  call  or  the  equivalent. 

quit  return  stack:  A  table,  maintained  in  memory 
by  ProDOS  16,  that  contains  the  User  ID's  of 
programs  that  want  to  be  reexecuted  after  the 
current  program  quits. 

radio  button:  A  common  type  of  control  in 

dialog  boxes.  Radio  buttons  are  small  circles 
organized  into  families — clicking  any  button  on 
turns  off  all  the  others  in  the  family,  like  the 
buttons  on  a  car  radio. 

RAM:  See  random-access  memory. 

random-access  memory  (RAM):  Memory  in 
which  information  can  be  referred  to  in  an 
arbitrary  or  random  order.  Programs  and  other 
data  in  RAM  are  lost  when  the  computer  is 
turned  off.  (Technically,  the  read-only  memory 
(ROM)  is  also  random  access,  and  what's  called 
RAM  should  correctly  be  termed  read-write 
memory)  Compare  read-only  memory. 


read-only  memory  (ROM):  Memory  whose 
contents  can  be  read,  but  not  changed;  used  for 
storing  firmware.  Information  is  placed  into  ROM 
once,  during  manufacture;  it  then  remains  there 
permanently,  even  when  the  computer's  power  is 
turned  off.  Compare  random-access  memory. 

rectangle:  One  of  the  fundamental  shapes  drawn 
by  QuickDraw  II.  Rectangles  are  completely 
defined  by  two  points — their  upper-left  and 
lower-right  corners  on  the  coordinate  plane.  The 
upper-left  corner  of  any  rectangle  is  its  origin. 

reentrant:  Said  of  a  routine  that  is  able  to  accept 
a  call  while  one  or  more  previous  calls  to  it  are 
pending,  without  invalidating  the  previous  calls. 
Under  certain  conditions,  the  Apple  IIGS 
Scheduler  manages  execution  of  routines  that  are 
not  reentrant. 

region:  An  arbitrary  area  or  set  of  areas  on  the 
QuickDraw  coordinate  plane.  The  outline  of  a 
region  must  be  one  or  more  closed  loops. 

RELOAD  segment:  A  segment  that  is  always 
reloaded  from  disk  when  a  program  is  executed, 
even  if  the  program  is  in  a  dormant  state  in 
computer  memory.  Some  programs  require 
RELOAD  segments  in  order  to  be  restartable. 

relocatable:  Characteristic  of  a  load  segment  or 
other  OMF  program  code  that  includes  no 
references  to  specific  address,  and  so  can  be 
loaded  at  any  memory  address.  A  relocatable 
segment  consists  of  a  code  image  followed  by  a 
relocation  dictionary.  Compare  absolute. 

relocation:  The  act  of  modifying  a  program  in 
memory  so  that  its  address  operands  correctly 
reflect  its  location  and  the  locations  of  other 
segments  in  memory.  Relocation  is  performed  by 
the  System  Loader  when  a  relocatable  segment  is 
first  loaded  into  memory. 

relocation  dictionary:  In  object  module  format,  a 
portion  of  a  load  segment  that  contains 
relocation  information  necessary  to  modify  the 
memory  image  portion  of  the  segment.  See 
relocation. 
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resource:  A  type  of  organization  for  certain 
components  of  Macintosh  files.  Resources 
provide  a  convenient  means  for  manipulating 
the  fixed  (unchanging)  parts  of  a  program  file. 

resource  editor:  A  program  for  editing  resources, 
especially  data  in  a  program,  without  having  to 
recompile  the  program. 

Resource  Manager:  The  Macintosh  toolbox 
component  that  retrieves,  manipulates,  and 
disposes  of  resources. 

restart:  To  reactivate  a  dormant  program  in  the 
computer's  memory.  The  System  Loader  can 
restart  dormant  programs  if  all  their  static 
segments  are  still  in  memory.  If  any  critical  part 
of  a  dormant  program  has  been  purged  by  the 
Memory  Manager,  the  program  must  be  reloaded 
from  disk  instead  of  restarted. 

restartable:  Said  of  a  program  that  reinitializes  its 
variables  and  makes  no  assumptions  about 
machine  state  each  time  it  gains  control.  Only 
restartable  programs  can  be  resurrected  from  a 
dormant  state  in  memory. 

RGB:  Abbreviation  for  red-green-blue,  a  method 
of  displaying  color  video  by  transmitting  the 
three  primary  colors  as  three  separate  signals. 
There  are  two  ways  of  using  RGB  with  computers: 
TTL  RGB,  which  allows  the  color  signals  to  take 
on  only  discrete  values;  and  analog  RGB,  which 
allows  the  color  signals  to  take  on  any  values 
between  their  upper  and  lower  limits. 

ROM:  See  read-ordy  memory. 

routine:  A  part  of  a  program  that  accomplishes 
some  task  subordinate  to  the  overall  task  of  the 
program. 

RTI:  Return  from  Interrupt,  a  65816  assembly- 
language  instruction. 

RTL:  Return  from  Subroutine  (Long),  a  65816 
assembly-language  instruction. 

RTS:  Return  from  Subroutine,  a  65816  assembly- 
language  instruction. 


SANE:  See  Standard  Apple  Numeric 
Environment. 

SANE  Tool  Set:  The  Apple  IIGS  tool  set  that 
performs  high-precision  floating-point 
calculations,  following  SANE  standards. 

scaled  font:  A  font  that  is  created  by  the  Font 
Manager  by  calculation  from  a  real  font  of  a 
different  size. 

scan  line:  A  single  horizontal  line  of  pixels  on 
the  screen.  It  corresponds  to  a  single  sweep  of 
the  electron  gun  in  the  video  display  tube. 

scanline  control  byte  (SCB):  A  byte  in  memory 
that  controls  certain  properties,  such  as  available 
colors  and  number  of  pixels,  for  a  scan  line  on 
the  Apple  IIGS.  Each  scan  line  has  its  own  SCB. 

Scheduler:  The  Apple  IIGS  tool  set  that  manages 
requests  to  execute  interrupted  software  that  is 
not  reentrant.  If,  for  example,  an  interrupt 
handler  needs  to  make  system  software  calls,  it 
must  do  so  through  the  Scheduler  because 
ProDOS  16  is  not  reentrant.  Applications 
normally  need  not  use  the  Scheduler  because 
ProDOS  16  is  not  in  an  interrupted  state  when  it 
processes  applications'  system  calls. 

Scrap  Manager:  The  Apple  IIGS  tool  set  that 
supports  the  desk  scrap,  which  allows  data  to  be 
copied  from  one  application  to  another  (or  from 
one  place  to  another  within  an  application). 

scroll:  To  move  an  image  of  a  document  or 
directory  in  its  window  so  that  a  different  part  of 
it  becomes  visible. 

scroll  bar:  A  rectangular  bar  that  may  be  along 
the  right  side  or  bottom  of  a  window.  Clicking  or 
dragging  in  the  scroll  bar  causes  the  view  of  the 
document  to  change. 

segment:  A  component  of  an  OMF  file,  consisting 
of  a  header  and  a  body.  In  object  files,  each 
segment  incorporates  one  or  more  subroutines. 
In  load  files,  each  segment  incorporates  one  or 
more  object  segments. 
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segment  kind:  A  numerical  designation  used  to 
classify  a  segment  in  object  module  format. 

self-booting:  Said  of  a  program  that  executes 
automatically  when  the  computer  is  turned  on  or 
reset. 

sequence:  A  series  of  commands  that  tells  the 
computer  what  notes  to  play  and  when. 

serial  interface:  A  standard  method,  such  as  RS- 
232,  for  transmitting  data  serially  (as  a  sequence 
of  bits). 

serial  port:  The  connector  for  a  peripheral 
device  that  uses  a  serial  interface. 

Shaston:  The  Apple  IIGS  system  font. 

shell:  A  program  that  provides  an  operating 
environment  for  other  programs,  and  that  is  not 
removed  from  memory  when  those  programs  are 
running.  For  example,  the  APW  Shell  provides  a 
command  processor  interface  between  the  user 
and  the  other  components  of  APW,  and  remains 
in  memory  when  APW  utility  programs  are 
running.  A  shell  is  one  type  of  controlling 
program, 

shell  application:  A  type  of  program  that  is 
launched  from  a  shell  and  runs  under  its  control. 
Shell  applications  are  ProDOS  16  file  type  $B5. 
In  APW,  compilers  and  certain  Shell  commands 
are  shell  applications  that  are  launched  from  the 
APW  Shell. 

shell  call:  A  request  from  a  program  to  the  APW 
Shell  to  perform  a  specific  function. 

shut  down:  To  remove  from  memory  or 
otherwise  make  unavailable,  as  a  tool  set  that  is 
no  longer  needed  or  an  application  that  has  quit. 

size  box:  A  small  square  in  the  lower-right  corner 
of  some  windows,  with  which  the  user  can  resize 
the  window.  The  size  box  corresponds  to  the 
grow  region. 

65C816:  The  version  of  the  65816  microprocessor 
used  in  the  Apple  IIGS.  The  65C816  is  a  CMOS 
device. 


65816:  A  general  term  for  the  type  of 
microprocessor  used  in  the  Apple  IIGS.  The 
65816  is  related  to,  but  more  advanced  than,  the 
6502  microprocessor.  It  has  a  l6-bit  data  bus  and^ 
a  24-bit  address  bus. 

65816  assembly  language:  A  low-level 
programming  language  written  for  the  65816 
family  of  microprocessors. 

6502:  The  microprocessor  used  in  the  Apple  II,  in 
the  Apple  II  Plus,  and  in  early  models  of  the 
Apple  lie.  The  6502  is  an  NMOS  device  with  an  8- 
bit  data  bus  and  a  16-bit  address  bus. 

640  mode:  An  Apple  IIGS  video  display  mode, 
640  pixels  horizontally  by  200  pixels  vertically. 

slot:  A  narrow  socket  inside  the  computer  where 
the  user  can  install  peripheral  cards.  Also  called 
an  expansion  slot. 

SmartPort:  A  set  of  firmware  routines  supporting 
multiple  devices  connected  to  the  Apple  IIGS  disk 
port. 

software:  A  collective  term  for  programs,  the 
instructions  that  tell  the  computer  what  to  do. 
Software  is  usually  stored  on  disks.  Compare 
firmware,  hardware. 

Sound  Tool  Set:  The  Apple  IIGS  tool  set  that 
provides  low-level  access  to  the  sound  hardware. 

source:  See  source  location. 

source  file:  An  ASCII  file  consisting  of 
instructions  written  in  a  particular  language,  such 
as  Pascal  or  assembly  language.  An  assembler  or 
compiler  converts  source  files  into  object  files. 

source  location:  The  location  (memory  buffer  or 
portion  of  the  QuickDraw  II  coordinate  plane) 
from  which  data  such  as  text  or  graphics  are 
copied.  Compare  destination  location.  See  also 
source  rectangle. 

source  rectangle:  The  rectangle  (on  the 
QuickDraw  II  coordinate  plane)  from  which  text 
or  graphics  are  taken  when  transferred 
somewhere  else.  Compare  destination  rectangle. 
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special  memory:  On  an  Apple  IIGS,  all  of  banks 
$00  and  $01,  and  all  display  memory  in  banks 
$E0  and  $E1  .  It  is  the  memory  directly  accessed 
by  standard-Apple  n  programs  running  on  the 
Apple  IIGS. 

spool  printing:  A  two-step  printing  method  used 
to  print  graphics  on  the  ImageWriter.  In  the  first 
step,  it  writes  out  (spools)  a  representation  of 
your  document's  printed  image  to  a  disk  file  or 
to  memory.  In  the  second  step,  this  information 
is  converted  into  a  bit  image  and  printed. 
Compare  draft  printing. 

S  register:  See  stack  register. 

stack:  A  list  in  which  entries  are  added  (pushed) 
and  removed  (pulled)  at  one  end  only  (the  top 
of  the  stack),  causing  them  to  be  removed  in  last- 
in,  first-out  (LIFO)  order.  The  stack  usually  refers 
to  the  particular  stack  pointed  to  by  the  658l6's 
stack  register.  Compare  queue. 

stack  pointer:  See  stack  register. 

stack  register:  A  register  in  the  65816  processor 
that  indicates  the  next  available  memory  address 
in  the  stack. 

Standard  Apple  Numerics  Environment 
(SANE):  The  set  of  methods  that  provides  the 
basis  for  floating-point  calculations  in  Apple 
computers.  SANE  meets  all  requirements  for 
extended-precision,  floating-point  arithmetic  as 
prescribed  by  IEEE  Standard  754  and  ensures 
that  all  floating-point  operations  are  performed 
consistently  and  return  the  most  accurate  results 
possible. 

standard  Apple  H:  Any  computer  in  the  Apple  II 
family  except  the  Apple  IIGS.  That  includes  the 
Apple  II,  the  Apple  II  Plus,  the  Apple  He,  and  the 
Apple  lie. 

Standard  File  Operations  Tool  Set:  The  Apple 
IIGS  tool  set  that  creates  a  standard  user  interface 
for  opening  and  closing  files. 


standard  linker  (APW):  One  aspect  of  the  linker 
supplied  with  APW.  The  operation  of  the 
standard  linker  is  automatic.  Compare  advanced 
linker. 

standard  window  parts:  The  window  features  that 
allow  the  user  to  scroll  through  the  data  in  the 
window,  change  the  window's  shape,  or  close  the 
window.  They  also  provide  information  about  the 
document  currently  displayed  in  the  window. 

START:  The  name  of  the  program  in  the 
SYSTEM/subdirectory  of  the  startup  disk  that  is 
launched  automatically  when  the  system  is 
booted.  START  is  typically  a  finder  or  program 
launcher. 

start  up:  To  get  the  system  or  application 
program  running. 

static  segment:  A  program  segment  that  must  be 
loaded  when  the  program  is  started,  and  cannot 
be  removed  from  memory  until  execution 
terminates.  Compare  dynamic  segment. 

static  text:  Text  on  the  screen  that  cannot  be 
altered  by  the  user. 

status  register:  A  register  in  the  65816 
microprocessor  that  contains  flags  reflecting  the 
various  aspects  of  machine  state  and  operation 
results. 

string:  A  sequence  of  characters.  See  C  string, 
Pascal  string 

structure  region:  An  entire  window;  its  content 
region  plus  its  frame  region. 

Style  dialog  box:  A  dialog  box  that  allows  the 
user  to  specify  formatting  information,  page  size, 
and  printer  options. 

styled  variation:  An  italicized,  boldfaced, 
underlined,  or  otherwise  altered  version  of  a 
plain-styled  character  or  font. 

subdirectory:  A  file  that  contains  information 
about  other  files.  In  a  hierarchical  file  system, 
files  are  accessed  through  the  subdirectories  that 
reference  them. 
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subroutine:  A  part  of  a  program  that  can  be 
exerted  on  request  from  another  pom  in  the 
p^am  and  that,  upon  completion,  returns 
control  to  the  point  of  the  request. 

Super  Hl-Res:  Either  of  two  high-resolution  Apple 

IIGS  display  modes.  320  mode  consists  of  an 

aSy of  pixels  320  wide  by  200  high,  with  16 

avalble'colors;  640  mode  is  an  array  640  wide 

by  200  high,  with  16  available  colors  (with 

restrictions). 

switcher.  A  controlling  program  that  rapidly 

ESS execution  among  several  applications. 

switch  event:  An  event  type  reserved  for  future 

uTtch  as  in  conjunction  with  a  switcher. 

symbolic  reference:  A  name  or  label  such  as  the 

name  of  a  subroutine,  that  is  used  to  refer  to  a 

Son  in  a  program.  When  a  P^^1^ 

all  symbolic  references  are  resolvedr *hen  ite 

program  is  loaded,  actual  memory  addresses  are 

patched  into  the  program  to  replace  the 

Symbolic  references.  (This  process  is  called 

relocation.) 

synthesizer:  (1)  A  hardware  device  capable  of 

bating  sound  digitally  and  converting  £  into  an 

analog  waveform  that  you  can  hear.  (2)  By 

analogy,  any  sound-making  entity,  such  as  the 

Note  Synthesizer  tool  set 

system  disk:  A  disk  that  contains  the  operating 

Astern  and  other  system  software  needed  to  run 

applications. 

astern  event  mask:  A  set  of  flags  that  control 

STevIntVs  get  posted  into  the  event  queue 

by  the  Event  Manager. 

system  failure:  The  unintentional  termination  of 

progTm  execution  due  to  a  severe  software  error. 

System  Failure  Manager:  A  part  of  the 
Miscellaneous  Tool  Set  that  processes  fatal  errors 
by  displaying  a  message  on  the  screen  and 
halting  execution. 


^.en.  ffle  .evek  A  nam be, b*^*"^ 
associated  with  each  open  ProDOS  16  file.  every 

ST.  Hie  ,3  op~4  ?-  ««  J£  *  fm  me 
svstem  file  level  is  assigned  to  it.  It  tne sys e 

Sa  controlling  program  can  easily  close  or 
flush  files  opened  by  its  subprograms. 
system  folder:  The  SYSTEM/subdirectory  on  a 
ProDOS  16  system  disk. 

system  library  prefix:  ProDOS  16  prefix  number 
7  It%ec!fSthe  directory  containing  library 
files  used  by  system  software 


the  Memory  Manager. 
system  menu  bar:  The  menu  bar  that  always 
Tia^s  at  the  top  of  the  screen  in  desktop 
"pptications.  It  contains  all  of  the ™n* 
used  functions,  in  menus  such  as  File,  Edit,  and 

on. 

system  prefix  (ProDOS  8):  The  one  prefix 

maintained  by  ProDOS  8. 

astern  software:  The  components  of  a  computer 
^r^portappUcationprog^by 

managing  system  resources  such  as  memory  and 

I/O  devices. 

system  window:  A  window  in  which  a  desk 

accessory  is  displayed. 

task  code:  A  numeric  value  assigned  to  the  result 

oTeach  event  handled  by  TaskMaster.  Compare 

event  code. 

task  mask:  A  parameter  passed  to  TaskMaster, 

^cS  whfch  types  of  events  TaskMaster  is  to 

respond  to. 
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TaskMaster:  A  Window  Manager  routine  that 
handles  many  typical  events  for  an  application. 
Applications  may  call  TaskMaster  instead  of 
GetNextEvent 

template:  A  data  structure  or  set  of  parameters 
that  defines  the  characteristics  of  a  desktop 
feature,  such  as  a  window  or  control.  The 
NewWindow  parameter  list  is  a  template  that 
defines  the  appearance  of  a  window  to  be 
opened  by  the  NewWindow  call. 

text-based  interface:  An  interface  between 
computer  and  user  in  which  all  screen  drawing 
(or  other  output)  consists  of  characters.  The  form 
of  each  character  is  stored  in  ROM  and  can  be 
involved  with  a  single  byte  of  data.  Compare 
graphic  interface. 

text  buffer:  A  1-bit-per-pixel  pixel  image  reserved 
for  the  private  use  of  the  QuickDraw  II  text- 
drawing  call. 

text  file:  A  file  consisting  of  the  ASCII 
representation  of  characters. 

text  mode:  One  of  16  possible  interactions 
between  pixels  in  text  being  drawn  to  the  screen 
and  pixels  on  the  screen  that  fall  under 
characters  being  drawn.  Compare  drawing  mode. 

Text  Tool  Set:  An  Apple  IIGS  tool  set  that 
provides  an  interface  between  Apple  II  character 
device  drivers  and  applications  running  in  native 
mode. 

320  mode:  An  Apple  IIGS  video  display  mode, 
320  pixels  horizontally  by  200  pixels  vertically. 

tick  count:  The  (approximate)  number  of  60th 
second  intervals  since  system  startup. 

title  bar:  The  horizontal  bar  at  the  top  of  a 

window  that  shows  the  name  of  the  window's 
contents.  The  user  can  move  the  window  by 
dragging  the  title  bar. 

tool:  See  tool  set 


toolbox:  The  collection  of  built-in  routines  on 
the  Apple  IIGS  that  programs  can  call  to  perform 
many  commonly  needed  functions.  Functions 
within  the  toolbox  are  grouped  into  tool  sets. 

tool  call:  A  call  to  a  function  within  a  tool  set. 

Tool  Locator:  The  Apple  IIGS  tool  set  that 
dispatches  tool  calls.  The  tool  locator  knows  and 
retrieves  the  appropriate  routine  when  you  make 
a  tool  call. 

Tool  Pointer  Table  (TPT):  A  table,  maintained  by 
the  Tool  Locator,  that  contains  pointers  to  all 
active  tool  sets. 

tool  set:  A  group  of  related  routines  (usually  in 
ROM)  that  perform  necessary  functions  or 
provide  programming  convenience.  They  are 
available  to  applications  and  system  software. 
The  Memory  Manager,  the  System  Loader,  and 
QuickDraw  II  are  Apple  IIGS  tool  sets. 

tool  table:  A  list  of  all  needed  tool  sets  and  their 
minimum  required  versions.  An  application 
constructs  this  table  in  order  to  load  its  RAM- 
based  tool  sets  with  the  LoadTools  call. 

track:  (1)  One  of  a  series  of  concentric  circles 
magnetically  recorded  on  the  surface  of  a  disk 
when  it  is  formatted.  Each  track  is  further  divided 
into  sectors.  Each  sector  can  hold  several  K  of 
data.  (2)  A  grouping  of  items  in  a  musical 
sequence.  The  Note  Sequencer  supports  multiple 
tracks  to  facilitate  writing  multi-instrument  music. 

transfer  mode:  A  specification  of  which  Boolean 
operation  QuickDraw  should  perform  when 
drawing.  See,  for  example,  XOR. 

TRUE:  Nonzero.  The  result  of  a  Boolean 
operation.  Opposite  of  FALSE. 

TTL  RGB:  A  type  of  color  video  consisting  of 
separate  red,  green,  and  blue  signals  that  can 
have  only  discrete  values. 
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typelD:  A  subfield  of  the  User  ID.  The  User  ID 
Manager  assigns  a  typelD  value  based  on  the 
type  of  program  (application,  tool  set,  and  so 
on)  requesting  the  memory. 

unhighlight:  To  restore  to  normal  display. 

Selected  controls,  menu  items,  or  other  objects 

may  be  highlighted  (usually  displayed  in  inverse 

colors)  while  in  use,  and  unhighlighted  when  not 

in  use. 

unload:  To  remove  a  load  segment  from 

memory.  To  unload  a  segment,  the  System 

Loader  does  not  actually  "unload"  anything;  it 

calls  the  Memory  Manager  to  either  purge  or 

dispose  of  the  memory  block  in  which  the  code 

segment  resides. 

unlock:  To  permit  the  Memory  Manager  to  move 

or  purge  a  memory  block  if  needed.  Opposite  of 

lock, 

immovable  See  fixed. 

unpack:  To  restore  to  normal  format  from  a 

packed  format. 

unpurgeable:  Having  a  purge  level  of  zero.  The 

Memory  Manager  is  not  permitted  to  purge 

memory  blocks  whose  purge  level  is  zero. 

update:  A  type  of  window  event,  signifying  that  all 
or  part  of  the  window  needs  to  be  redrawn. 

update  event:  An  event  posted  by  the  Window 
Manager  when  all  or  part  of  a  window  needs  to 
be  redrawn. 

update  region:  A  description  of  the  part  of  a 
window  that  needs  to  be  redrawn.  The  Window 
Manager  keeps  track  of  each  open  window's 
update  region. 

User  ID:  An  identification  number  that  specifies 
the  owner  of  every  memory  block  allocated  by 
the  Memory  Manager.  User  ID's  are  assigned  by 
the  User  ID  Manager. 


User  ID  Manager:  A  part  of  the  Miscellaneous 

Tool  Set  that  is  responsible  for  assigning  User 

ID'S  to  every  block  of  memory  allocated  by  the 

Memory  Manager. 

vector:  A  location  that  contains  a  value  used  to 

find  the  entry  point  address  of  a  subroutine. 

vertical  blanking:  The  interval  between  successive 

screen  drawings  on  a  video  display.  It  is  the  time 

between  drawing  the  last  pixel  of  the  last  scan 

line  of  one  frame  and  the  first  pixel  of  the  first 

scan  line  of  the  next  frame. 

visible  region:  The  part  of  a  window  that's 

actually  visible  on  the  screen.  The  visible  region 

is  a  GrafPort  field  manipulated  by  the  Window 

Manager. 

voice:  Any  one  of  16  pairs  of  oscillators  in  the 

Ensoniq  sound  chip  on  the  Apple  IIGS. 

volume  name:  The  name  of  the  volume  directory. 

wedge:  A  filled  arc,  one  of  the  fundamental 
shapes  drawn  by  QuickDraw  II. 

window:  A  rectangular  area  that  displays 
information  on  a  desktop.  You  view  a  document 
through  a  window.  You  can  open  or  close  a 
window,  move  it  around  on  the  desktop,  and 
sometimes  change  its  size,  scroll  through  it,  and 
edit  its  contents.  The  area  inside  the  window's 
frame  corresponds  to  the  port  rectangle  of  the 
window's  GrafPort. 

window  frame:  The  outline  of  the  entire  window 
plus  certain  standard  window  controls. 
Window  Manager:  The  Apple  IIGS  tool  set  that 
updates  and  maintains  windows. 
window  menu  bar:  A  menu  bar  that  appears  at 
the  top  of  the  active  window,  below  the  system 
menu  bar.  Window  menu  bars  can  contain 
document  titles,  applications,  and  functions. 

window  record:  The  internal  representation  of  a 
window,  where  the  Window  Manager  stores  all  the 
information  it  needs  for  its  operations  on  that 
window. 
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word:  On  the  Apple  IIGS,  a  1 6-bit  (2-byte)  data 
type.  Compare  long  word. 

x  flag:  One  of  three  flag  bits  in  the  65816 
processor  that  programs  use  to  control  the 
processor's  operating  modes.  In  native  mode,  the 
setting  of  the  x  flag  determines  whether  the  index 
registers  are  8  bits  wide  or  16  bits  wide.  See  also 
e  flag  and  m  flag. 

XOR:  Exclusive-OR.  A  Boolean  operation  in 
which  the  result  is  TRUE  if,  and  only  if,  the  two 
items  being  compared  are  unequal  in  value. 

X  register:  One  of  the  two  index  registers  in  the 
65816  microprocessor. 

Y  register:  One  of  the  two  index  registers  in  the 
65816  microprocessor. 

zero  page:  The  first  page  (256  bytes)  of  memory 
in  a  standard  Apple  II  computer  (or  in  the  Apple 
IIGS  when  running  a  standard  Apple  II  program). 
Because  the  high-order  byte  of  any  address  in 
this  part  of  memory  is  zero,  only  a  single  byte  is 
needed  to  specify  a  zero-page  address.  Compare 
direct  page. 

zoom  box:  A  small  box  with  a  smaller  box 
enclosed  in  it,  found  on  the  right  side  of  the  title 
bar  of  some  windows.  Clicking  the  zoom  box 
expands  the  window  to  its  maximum  size;  clicking 
it  again  returns  the  window  to  its  original  size. 

zoom  area:  The  window  subregion  that 
corresponds  to  the  zoom  box. 
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Here  are  four  categories  of  books  that  can  help  you  learn  more 
about  desktop  programming  on  the  Apple  IIGS.  We  list  only  a  few 
titles  in  each  category;  many  more  books  are  available. 

Several  of  the  books  listed  below  are  part  of  the  Apple  IIGS 
technical  suite.  See  "Introduction  to  the  Programmer's 
Introduction"  for  other  titles  in  the  suite. 


Apple  IIGS  technical  manuals 

In  this  category,  the  most  important  book  for  writing  programs  is 
the  toolbox  reference  manual.  You  cannot  write  desktop 
applications  without  it. 

Apple  IIGS  Firmware  Reference.  Reading,  Mass.:  Addison-Wesley, 
1987. 

Apple  IIGS  Hardware  Reference.  Reading,  Mass.:  Addison-Wesley, 
1987. 

Apple  IIGS  ProDOS  16  Reference.  Reading,  Mass.:  Addison-Wesley, 
1987. 

Apple  IIGS  Toolbox  Reference,  Volumes  1  and  2.  Reading,  Mass.: 
Addison-Wesley,  1987. 

Technical  Introduction  to  the  Apple  IIGS.  Reading,  Mass.: 
Addison-Wesley,  1986. 
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Programming  manuals 

This  category  includes  both  books  and  development 
environments.  APW  (Apple  IIGS  Programmer's  Workshop)  is 
essential  if  you  plan  to  compile  and  modify  HodgePodge.  The 
usefulness  of  the  other  books  depends  on  which  language(s)  you 
are  programming  in.  This  list  is  by  no  means  complete: 
additional  books  for  these  and  other  Apple  IIGS  programming 
languages  are  available. 

♦  APDA:  Books  marked  "[APDA]"  are  distributed  through  the 
Apple  Programmer's  and  Developer's  Association.  See 
Chapter  9. 

Apple  IIGS  Programmer's  Workshop  Assembler  Reference. 
Cupertino,  Calif.:  Apple  Computer,  Inc.,  1987.  [APDA] 

Apple  IIGS  Programmer's  Workshop  C  Reference.  Cupertino, 
Calif.:  Apple  Computer,  Inc.,  1987.*  [APDA] 

Apple  IIGS  Programmer's  Workshop  Reference.  Cupertino,  Calif.: 
Apple  Computer,  Inc.,  1987.*  [APDA] 

Eyes,  David,  and  Ron  Lichty.  Programming  the  65816,  Including 
the  6502,  65C02,  and  65802.  New  York:  Prentice  Hall  Press,  1986. 

Jensen,  Kathleen,  and  Niklaus  Wirth.  Pascal  User  Manual  and 
Report.  3rd.ed.  New  York:  Springer- Verlag,  1982. 

Kernighan,  Brian  W.,  and  Dennis  M.  Ritchie.  The  C  Programming 
Language.  Engelwood  Cliffs,  N.  J.:  Prentice-Hall,  1978. 

ORCA/  Pascal:  A  Pascal  Compiler  and  Development  System  for 
the  Apple  IIGS.  Albuquerque,  N.  M:  The  Byte  Works,  Inc.,  1987.* 

TML  Pascal  for  the  Apple  IIGS:  User's  Guide  and  Reference 
Manual  (APW  version).  Jacksonville,  Fla.:  TML  Systems,  Inc 
1987.' 

*  Includes  software. 
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All-Apple  manuals 

Here  note  especially  the  Human  Interface  Guidelines  book— it 
contains  a  wealth  of  information  to  help  you  design  your  program 
for  maximum  effectiveness  and  ease  of  use. 
Apple  Numerics  Manual.  Reading,  Mass.:  Addison-Wesley,  1987. 
Human  Interface  Guidelines:  The  Apple  Desktop  Interface. 
Reading,  Mass.:  Addison-Wesley,  1987. 


Macintosh  programming  manuals 

These  books  are  included  because  many  desktop  concepts, 
although  developed  originally  for  the  Macintosh,  are  directly 
applicable  to  the  Apple  IIGS.  Remember,  though,  that  details  of 
implementation  are  often  quite  different! 

Chernicoff,  Stephen.  Macintosh  Revealed.  Volume  One:  Unlocking 
the  Toolbox.  Hasbrouck  Heights,  N.  J.:  Hayden  Book,  1985. 

Chernicoff,  Stephen.  Macintosh  Revealed.  Volume  Two: 

Programming  With  the  Toolbox.  Hasbrouck  Heights,  N.  J.: 

Hayden  Book,  1985. 
Inside  Macintosh,  Volumes  I-V  Reading,  Mass.:  Addison-Wesley, 

1987. 
Programmer's  Introduction  to  the  Macintosh  Family.  Reading, 

Mass.:  Addison-Wesley,  1988. 
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programming  techniques    141 
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alert  windows   110,111,116,136 
ALLOCJNTERRUPT     272 
Alternate  Display  Mode   157 
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applEvt  69 

Apple  Certified  Developer 
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174 
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defined  xxi 
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Apple  IIGS.  See  also  ProDOS  8; 
ProDOS  16;  programming 
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built-in  I/O   8-9 
clock-calendar  9 
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compatibility  with  standard  Apple 

II    9-10,  291-292 
Control  Panel   9 
disk  port  8 
execution  modes    4 
firmware  xviii 
game  I/O  connectors   2,  8 
general   xiii-xxii,  2-27 
hardware  xvii 
keyboard   2,  8 
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microprocessor   2,  3-5 
programming  (general)  xvii 
registers    4 

serial  I/O  ports   2,  8,  9 
slots    2,  6,  8-9 


sound   2,  8,  174 
video    2,  6-7 
Apple  IIGS  Debugger    224, 

248-253 
Apple  IIGS  Programmer's 

Workshop  (APW)  xviii,  26-27, 
65,  205,  220-225,  296 
advanced  linker   223,  235,  236, 

238 
assembler   xviii,  222 
C  compiler  xviii,  222 
editor    222 

language  considerations   225 
linker    222 

parameter-passing    225 
program  descriptions    221-224 
Shell    199,  221-222,  259,  261 
standard  linker    223,  235,  238 
utilities    223 

Compact    223 
Crunch    223 
DumpOBJ    223 
Equal    224 
Files    224 
Init    224 
MacGen  224 
MakeLib    224,  238 
Search    224 
Apple  IIGS  Toofbox  xviii,  17-22, 
42,  62-106,  108-144, 
146-183.  See  also  tool  sets  or 
specific  routine/tool  set 
calls  (typographic  convention  for) 

xxii,  36 
compared  to  Macintosh   284-289 
constants    38 
data  structures   38 
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errors   65,  66,  67 
macros   65 

memory  requirements    5 
Apple  II  Plus   xxi,  8,  9,  290 
application-defined  events   69,  73 
application  prefix  209 
applications    256-259 
hybrid    292-293 
programming  techniques   26, 

228-229,   256-259 
restartable    259 
self-booting    257-258 
application  system  disk    300-301 
application  windows  111 
APW.  See  Apple  IIGS 

Programmer's  Workshop 
arc  (QuickDraw  II)  87,  91 
ascent/ascent  line    93 
AskUser    59,  121,  163,  211,  306 
assembler  (APW)  xviii,  222 
assembly  language   xiv,  4,  65,  225, 
234 
HodgePodge  and    65-66,  190, 

202,  311-376 
programming  examples    190, 
193,  239-246,  263,  265, 
311-376 
programming  techniques   4, 

283-284,   290 
typographic  convention  for  xxii 
attrAddr    187 
attrBank    187 
attrFixed   187 
attributes  word    188 
attrLocked    187 
attrNoCross    187 
AttrNoSpec    187 
attrPage    187 
attrPurge    187 
auto-key  events    69,  71-72 
autoKeyEvt  69 
auxID  field    192-194 
auxiliary  type  field  (ProDOS)   217 
auxiliary  type  file  attributes    217, 
218 


B 

background  colors  92 
background  pattern  85 


background  pixels  93 

background  procedure    173 

backup  bit   215 

bank-boundary  limited    187 

banks.  See  memory  banks 

bank  zero   4,  6,  192,  203,  248, 
267-270,   293-296 

base  line   93 

batch  mode    13 

Battery  RAM  routines    181 

BeginUpdate    115,  118,  134 

bit  images    286 

bit  planes   98 

black  and  white  drawing,  QuickDraw 

II     103 
blocks.  See  memory  blocks 
boot  prefix    209 
bottom  scroll  bar    110 
boundary  rectangle    80-84,  103 
boundsRect    80 

breakpoints,  (debugging)    250-251 
built-in  interrupt  handler   267 
built-in  I/O    2,  8-9 
Busy  flag    157,  182,  183 
buttons    125,  128,  132-135 


CalcMenuSize    154,  155,  165 
Cancel  button    132,  133,  139 
carry  bit.  See  c  flag 
Caution  Alert    135 
C  compiler  (APW)  xviii,  222 
CDA.  See  classic  desk  accessory 
Certified  Developer    278-279 
c  flag  66 
CHANGE_PATH     214 

character  devices    173 

character  image   93 

character  origin  93 

characters    92,  93-94 

character  width  93 

check  boxes    125,  128 

CheckDiskError    136,  140, 
308-310 

CheckFrontW  50,  116 

CheckToolError    46,  306-307 

ChooseFont    97 

Choose  Printer  command  (File 
menu)    32,  166,  289 


Chooser    167,  289 
chunky  pixel  organization  98 
circles   90 

C  language  xiv,  xviii,  65,  202,  225, 
230,  234,  259 
HodgePodge  and    377-412 
programming  examples    190, 
377-412 
classic  desk  accessory, 

programming  examples    263 
classic  desk  accessory  (CDA)    156, 
247,  262,  300.  See  also  desk 
accessories;  new  desk 
accessory 
supporting    157 
writing   263 
CLEAR_BACKUP_BIT     215 
Clear  command  (Edit  menu)    32 
clicking  (mouse)    14,  15,  48,  110 
Clipboard   32,  92,  159,  160,  l6l 
clipping   77,  81-82,  83,  105,  136 
clipping  region   81,  82,  84 
clipRgn   82 
clock-calendar  9 
clock  (microprocessor)  9 
clock  (real-time)  9 
clock  routines    181 
clock  speeds    4,  269,  271,  290 
CLOSE    210,  211,  213 
close  box    48,  110,  111,  114 
Close  command  (File  menu)   32 
CIoseDialog    134,  144 
CloseNDA    158 
CloseNDAbyWinPtr   57,  158 
ClosePort    97 
close  routine  (NDA)   265 
Close  Window  57,  114 
closing  files   210 
color  palette    7,  99-100 
colors    98-103 
dithered    101-103 
QuickDraw  II   98-103 
Super  Hi-Res    7,  98 
window  frame   111 
color  tobies   7,  99-100 
command-line  interface    13 
commands.  See  specific  command 
compaction    188 
Compact  utility  (APW)   223 
compatibility  (Apple  II)    9-10 
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compiler  xviii,  222 

complete  system  disk    298-300 

constants 

event  codes    69 
memory-block  attributes    187 
task  codes   74 
toolbox-defined    38,  50 
constructing  menus    149-152 
content  region    112,  114,  129 
control  action  procedure   118 
Control-Apple-Escape   73 
control  definition  procedure    130 
controlling  programs    197,  199, 

259-260 
controlling  user  access  to  files    218 
Control  Manager    20,  64,  71,  117, 

124-131,  158,  264    288 
control  manipulation  (HodgePodge) 

130 
Control  Panel   9,  157,  174 
control-related  events, 

programming  techniques    129 
controls    20,  116,  117,  124-131 
active    128,  129 
custom    130 
events  and    129-130 
frame    129 
highlighting    128 
inactive    128 
invisible    128 
types  of    124-125 
value    125,  128,  130 
windows  and  129 
coordinate  plane   76,  77-79,  80 
locations  on  78 
size  of  77 
coordinates 

global   70,  77,  82-84 
local    77,  82-84,  103,  105, 
117-118 
Copy  command  (Edit  menu)   32, 

141,  159,  160 
COPY  mode    87 
CopyPixels    103 
CREATE     210,  213 
Crunch  utility  (APW)  223 
C  strings    92,  287 
CtlShutDown  58 
CtlStartUp  45 
cursor    116 


cursor  keys   8 

custom  controls    130 

custom  menus    149 

custom  windows   111 

Cut  command  (Edit  menu)   32, 

141,  159,  160 
cutting  and  pasting    159-161 

internally   160 

large  amounts  of  data    161 

private  scrap   l6l 

programming  techniques 
160-161 

publicly  160 


data  area    105,  112,  117 
Data  Bank  register    294,  295 
data  structures    277 

initializing  (HodgePodge)   38-41 
toolbox-defined   38 
DEALLOCJNTERRUPT     272 
debugging    246-254 
with  Apple  IIGS  Debugger 

248-253 
with  desk  accessories    246-247 
with  Monitor  program   247-248 
default  button 
alert  box    135 
dialog  boxes    139 
default  prefix    208,  209 
default  properties  (windows)   108 
definition  procedures   51,  109,  130, 

136,  149 
delete    141 
DeleteMltem    154 
Deref    190 

dereferencing    189,  190 
descent/descent  line    93 
desk  accessories   21,  47,  75, 

156-158,  182.  See  also  classic 
desk  accessory;  new  desk 
accessory 
Apple  menu  and   31 
debugging  with    246-247 

246-247 
HodgePodge  and    158 
Macintosh    156,  289 
programming  techniques 
262-265 


supporting    156-158 
TaskMaster  and    158 
writing    262-265 
desk-accessory  event    69 
deskAccEvt   69 
Desk  Manager  21,  47,  64,  71, 

156-158,  182,  262-265 
desk  scrap   21,  141,  159 
data  types    160 
on  disk   160 
DeskShutDown   58,  158 
DeskStartUp   45,  158 
desktop,  programming  techniques 

10 
desktop  applications    10,  13,  124 
desktop  features,  supporting ' 

156-161 
desktop  interface   xviii,  xix-xx, 

10-13,  20-21,  257 
desktop-interface  tool  sets    20-21 
DESTROY    210,  213 
destroying  files    210 
Developer  Technical  Support   279 
device-driver  events    69,  73 
device  drivers    69,  166,  173 
device  independence    12 
device-interface  tool  sets    21 
DIALOG.  ASM   353-360 
dialog  boxes    21,  131-136 
default  button    139 
message    135 
modal    133,  139 
modeless    133,  136 
DIALOG. cc    400-404 
dialog  items    137-140 

defining  with  a  template    140, 

285 
disabling   138 
display  rectangle    137,  139 
inactive  controls  as    138 
invisible    138 
item  ID    137,  139 
item  type    137,  138 
Dialog  Manager   21,  116,  131-144, 

308 
DIALOG. pas   429-433 
dialog  records   137 
dialogs,  programming  techniques 

141 
DialogShutDown  58 
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DialogStartUp  45 
dialog  windows   116,136 
dials    125 

digital  oscillator  chip  (DOQ  8,  175 
direct  page    4,  202,  203,  283 
direct-page/stack  segment 
202-207,  260,  262 
ProDOS  16  default   206 
direct-page/stack  space    192,  203, 
260,  296 
location  and  arrangement   204 
for  tool  sets   42 
direct  register    4,  203,  262,  293, 

294 
disabling 
dialog  items    138 
interrupts    293 
menus  and  menu  items    116 
148 
disassembling    248 
disassembly,  watching  while  running 

249 
disk  port   8 
disks    14,  298-301 
Disk  II,  slot  for   9 
DispFontWindow  53 
display  rectangle  dialog  items    137, 

139 
DisposeAll    193,  194 
DisposeHandle   57,  190 
disposing  of  memory  handles    194, 

277 
dithered  colors    101-103 
dividing  line  (menus)    148 
DoAboutltem  55,  142 
DOC  (digital  oscillator  chip)  8,  175 
DoChooseFont    97,  121,  305 
DoChooserltem  56,  167 
DoCloseltem  56,  57 
document  coordinates    83 
document  window    110,  111,  133 
DoMenu   54,  153 
DoOpenltem    55,  120,  163,  305 
DoPrintltem  56,  170 
DoQuitltem   56 
dormant    200,  259 
DoSaveltem   56,  164,  213 
DoSetMono   56 
DoSetupItem    168 
DoSetUpItem  56 


DoTheOpen    121,  211,  305 

double-clicking  (mouse)   71 

Double  Hi-Res   7 

DoWindow   56 

down  arrow  (scroll  bar  part)  126 

draft  printing    171 

drag  area/dragging   71,  110,  114 

DragWindow  114,  115 

DrawDialog  134 

drawing  contents  of  windows 

115-116 
drawing  mask   85 
DrawMenuBar  47,  154,  155 
DrawString   44,  94,  106,  143 
DrawTopWindow    170 
driverEvt   69 
drivers.  See  device  drivers 
DumpOBJ  utility  (APW)   223 
dynamic  segments    23,  25,  195, 
196,  200,  232 
programming  examples    245 
unloading   246 


EDASM  assembler    296 
editable  text    138 
Edit  menu    32,  133 

Clear  command    32 

Copy  command   32,  141,  159, 
160 

Cut  command    32,  141,  159,  160 

Paste  command    32,  141,  159, 
161 

Undo  command  32,  277 
editor  (APW)   222 
8-bit  Apple  II.  See  standard  Apple 

II 
80-column  text  display   6,  260 

slot  for   8 
EMShutDown  58 
EMStartUp  43 
emulation  mode   4,  9,  173,  269, 

291,  293 
EndUpdate    115,  134 
EOF    214 

Equal  utility  (APW)   224 
erasing  (QuickDraw  II)  87,  91 
error  handling  (HodgePodge) 
306-310 


errors 
Apple  IIGS  Toolbox    65,  66,  67 
printing    172 
testing  for    277 
EVENT. ASM    330-336 
event. cc   385-389 
event  code    69,  73 
event-driven  programming 
techniques    13-16,  51 
event  handling    15-16,  67-75 

51-57 
event  loop.  See  main  event  loop 
Event  Manager    16,  20,  48,  63, 

67-75 
event  mask    70,  74,  265 
event. pas   422-424 
event  queue    68-70 
event  records    67,  70 
events    48.  See  also  specific  event 
compared  to  interrupts    67 
controls  and    129-130 
defined    14,  67 
types  of    69-70,  74 
execution  modes.  See  emulation 

mode;  native  mode 
Exerciser  (ProDOS  16)    253-254 
expansion  memory    6 
extended  task  event  record    54,  74, 

153 
extended  type    179 
external  references    197 


fields  within  records  36 
file  attributes    214 

access    215 

auxiliary  type    217 

creation  and  last-modification  date 
and  time    215 
File  menu    32,  133,  166 

Choose  Printer  command    32, 
166,  289 

Close  command    32 

Open  command  32 

Page  Setup  command    32 

Print  command    32 

Quit  command   32,  58 

Save  As  command    32 

Save  command    50 
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filename    208 
files    215 

accessing    162-165 
closing   210 

controlling  user  access  to   218 
creating    210 
destroying    210 
flushing    210 
HodgePodge  and    33,  34 
I/O  buffer    210 
opening    162,  210 
reading    211-214 
saving    164 
writing    211-214 
Files  utility  (APW)   224 
file  type    215-217,  256 

$04    218 

$06    218 

$B0    218 

$B3    256-259,  261,  297 

$B5    256,  261-262 

$B6    256,  266,  300 

$B7    256,  266,  300 

$B8    256,  265,  300 

$B9    256,  263,  300 

$BA    256,  300 

$C1    215,  218 
filling  (QuickDraw  II)  87,  91 
fill  mode    100 
FindControl    129 
FindMaxWidth    105 
FindWindow   74,  114,  115,  129, 
firmware  xviii,  294 
FixAppleMenu    47,  158 
fixed  address  (memory-block 

attribute)    187 
fixed  bank  (memory-block 

attribute)    187 
fixed  (memory-block  attribute) 

187,  189,  195 
fixed  type  (Integer  Math)    179 
FixMenuBar   47 
flag  word  (QUIT)  202 
FLUSH    210 
flushing  files   210 
FMShutDown   58 
FMStartUp   46 
FONT. asm   361-366 
FONT.cc    405-408 
font  families   95 


font  height   93 

Font  Manager    21,  64,  92,  94-96 

font  name    95 

font  number   95 

font  .  pas   434-436 

fonts    21,  34,  92,  94-97 

where  stored  on  disk   96 
font  size   95 
Fonts  menu    33 
font  strike    94 
font  style    96 
font  subsitution    167 
font  windows,  HodgePodge  and 

34,  53,  104-106,  305 
foreground  color  92 
foreground  pixels   93 
frac  type  (Integer  Math)    179 
frame    81 

alert  window  110 
colors    111 
controls    129,  130 
document  window   110 
region    112 

scroll  bars    117,  129,  288,  289 
window  109 
framing  (QuickDraw  II)  87,  91 
free-form  synthesizer    176 
FrontWindow   57,  154,  165,  170 
full  pathname    208 
function  number  (tool  set)   66,  274 
FWEntry    294 


152 


game  I/O  connectors    2,  8 
generators  (sound)    176 
GET_EOF    214 
GetFamlnfo    97,  105 
GET_FILE_INFO      214 
GetFontFlags     105 
GetFontlnfo    105,  123 
GET_LEVEL     211 
GET.MARK    214 
GetNewModalDialog   134,  142 
GetNextEvent    48,  68,  70,  73,  74, 
113,  114,  129,  152,  153,  286 
GetPen    106 
GetPort    52,  53,  97,  134 
GET_PREFIX     209 
GetTick    181 


GetWRefCon    52,  53,  57,  154,  165, 

171 
global  coordinates   70,  77,  82-84 
global  page  (ProDOS  8)   292,  296 
GLOBALS.ASM    373-376 
GLOBALS.PAS    152,443-446 
global  symbols    238 
GLU.  See  Sound  GLU 
go-away  box/area    110,  114 
GrafPort    81-82,  103,  108,  136 

printing    170 

relation  to  windows   108-109 
graphic  ports   76,  81,  103 
graphics  tablets   8 
grow  box/area   48,  114 
GrowWindow  114 


H 

handles    189,  190 

hardware.  See  Apple  1IGS 

HeartBeat    181 

HeartBeat  Interrupt  Task  queue 

181 

HidePleaseWait    46,  134 

HideWindow  114 

hierarchical  file  system    288 

high-level  languages    65    282-283, 
290 

highlighting   72,  116,  128,  153 

high-order  byte,  of  handles    190 

HiliteMenu   54 

Hi-Res    7 

Hi-Res  video  display   7 

HiWord  54 

HLock    104,  211 

HodgePodge    30-60.  See  also 
specific  subroutine 
"About..."  dialog  box    142-144 
assembly  language    65-66,  190, 

202,  311-376 
auxiliary  type    218 
C    377-412 

code-listing  conventions  xxii,  36 
control  manipulation   130 
desk  accessory  support    158 
differences  between  the 
languages   69,  74,  105 
direct-page/stack  space    206 
Edit  menu  disabled    161 
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error  handling   306-310 

event  handling    51-57 

files   33,  34 

font  windows   34,  53,  104-106, 
305 

general  description  xx 

languages   35 

Macintosh  resource  equivalents 
285 

main  event  loop    48-50 

main  program   36,  37 

memory-block  attributes    188 

menus    31-33,  47,  153 

mouse  events  and    71 

organization  of  35-36 

Pascal    36,  413-446 

picture  files    215-217,  218 

picture  windows  33,  52-53, 
103-104,  305-306 

QuickDraw  II  coordinates  and  82 

QUIT    202 

scrolling  and   117 

shutting  down    57,  58-59 

starting  up    38-47,  64 

subroutines    35,  59-60,  302-304 

System  Loader  and    195 

TaskMaster  and    51-53,  75,  286 

update  routine    116 

User  ID  use    193 

versions  of   35 

windows    56-57,  72,  120-124 
horizontal  blanking  100 
HP. asm    312-314 
HP.cc    378-381 
hp.h    411-412 
HP. pas    414-418 
Human  Interface  Guidelines 

xix-xx,  11-13,  139,  146,  277 
HUnLock    104,  211 
hybrid  applications   292-293 

I 

icons    10,  285,  286 
ID.  See  item  ID;  menu  ID;  User  ID 
image  pointer   80 
image  width   80 
ImageWriter    167 
inactive  controls    128 
as  dialog  items    138 


inactive  windows  115 
index  registers    4,  294 
information  bar   110 
INIT.ASM    315-323 
InitCursor    124,  165,  170,  309 
InitGlobals   35,  39-41,  150 
initialization  files  256,  266 
initialization  segment    196 
initializing  data  structures 

(HodgePodge)    38-41 
initializing.  See  starting  up 
Initial  Load   260 
ink  routine  (NDA)   264 
Ink  utility  (APW)   224 
InsertMenu    47 
InsertMItem    154,  155 
InstallFont    105,  123 
instrument    177 
Int2Hex    307,  309 
Integer  Math  strings    179 
Integer  Math  Tool  Set    22,  179 
integer  type  (Integer  Math)    179 
interactive  programming    13,  14 
international  markets   277 
interrupt  control  routines    181 
interrupt  environment    269 
interrupt  handlers    182,  183,  256, 

267-272 
interrupt  mode  (Note  Sequencer) 

178 
interrupts    176,  177,  178,  267 

compared  to  events    67 

disabling  293 
IntToString    105,  122,  165 
InvalRgn    117,  118 
inverting  (QuickDraw  II)   87,  91 
invisible  controls    128 
invisible  dialog  items    138 
I/O.  See  also  slots 

buffer  files    210 

built-in   2,  8-9 

serial  ports  8 
IO.ASM    371-372 
item  character  (menu  and  item 

lines)    150 
itemDisable    138 
item  ID 

dialogs    137,  139 

menus    54,  151-152,  155 
items 


dialog    137-140 

menus    149 

Note  Sequencer    178 


Job  dialog  box    169 

joysticks    8 

JSL    294 

JSR    294 

Jump  Table    196,  198 


keyboard   2,  8,  10 

keyboard  equivalents    148,  153 

key-down  events    15,  16,  69, 

71-72,  73 
keyDownEvt   69 
KIND    205 


language  considerations  (APW)  225 

LaserWriter   167 

launching  under  ProDOS   16 

200-202 
leading  93 
LEShutDown    58 
LEStartUp    45 
LETextBox     142 
LETextBox2     142 
library  dictionary  segment   238 
library  files    238-239 
licensing  Apple  software   279 
LineEdit  scrap    141,  l6l 
LineEdit  Tool  Set    21,  64,  138,  139, 

141-142 
line  (QuickDraw  II)  87,  88-89 
LinkEd    205,  234 
assigning  load  segments  with 

236 
linker  (APW)    222,  223,  235-238 
Lisa    14 

list  controls    131 
List  Manager   20,  64,  131 
lists    130-131 
ListShutDown    58 
ListStartUp    46 
Loader  Dumper    247,  249,  250 


484 


Index 


load  files    23,  26,  196,  226-229 

order  of  load  segments  in    235 
loading 
applications  (System  Loader) 

198,  199 
relocatable  segments  (System 

Loader)    197 
segments     198 
tool  sets    63 
LoadOne    164,  211,  306 
load  segments    194-195,  196,  230, 
231-234 
assigning  with  LinkEd  file   236 
assigning  in  source  code 

234-236 
characteristics  of   232 
difference  from  object  segments 

230 
dynamic    232 
memory  blocks  and    194 
number  of   232 
order  in  load  file   235 
types  of  (System  Loader)    196 
LoadTools   42,  44,  63 
local  coordinates   77,  82-84,  103, 

105,   117-118 
local  references    197 
location  information  76,  79 
Loclnfo  record   76,  79,  81,  103 
locked  handles    187,  189,  195,  277 
longint  type  (Integer  Math)    179 
LoWord  43,  54,  121,  123 


M 

MacGen  utility  (APW)  224 
Macintosh    13,  14,  17,  167,  180 

Control  Manager   288 

converting  programs  to  the  Apple 
IIGS     282-289 

desk  accessories    156,  289 

file  system    287-288 

Memory  Manager  288 

Print  Manager   289 

QuickDraw  286-287 

resources    285 

Standard  File  Package    289 

TaskMaster  not  available   286 

toolbox  compared  to  Apple  IIGS 
284-289 


Window  Manager  288 
macros    222   65 
MainEvent    35, 36,  50 
main  event  loop    14-15,  16,  48,  67 

HodgePodge  and    48-50 
mainID    192 
main  program  (HodgePodge)   36, 

37 
main  routine   233 
MakeATemplate    140,  310 
MakeLib  utility  (APW)   224,  238 
manager.  See  tool  sets  or  specific 

tool  set 
ManyWindDialog    120 
Mark   214 

master  color  values   98 
master  User  ID    192,  193 

DisposeAll  and   194 
math  tool  sets    22,  178-180 
maximum  segment  size    23 
memory    2,  4,  5-6,  76 
allocatable  by  Memory  Manager 

191 
allocation    191-194 
compaction    188 
disposal    193 
minimum  configuration   5 
RAM  expansion   5 
requirements  (Apple  IIGS 

Toolbox)   5 
ROM  expansion  5 
special    187 
memory  banks    6 
$00   4,  6,  192,  203,  248,  267, 

270,  293-296 
$01    6,  295 
$E0    6,  295 
$E1    6,  267,  295 
memory  blocks    187,  197,  247 
attributes    187,  188 
disposing  of   194,  277 
handles  to    189 
load  segments  and    194 
pointers  to    189 
purgeable    194,  233 
unlocking   194 
memory  fragmentation    188 
memory  image    228 
Memory  Manager  20,  22,  23,  42, 
63,  180,  186-195,  288 


Memory  Mangier   247 

memory  protection  ranges,  using 

252 
MENU. ASM    324-329 
menu  bar    115,  146,  147,  152 
MEND.CC    382-384 
menu-event  handling 

(HodgePodge)    54-56 
menu  ID    54,  55,  151-152,  155 
menu  interface    13 
menu  items    146 
disabled    148 

keyboard  equivalent    149,  153 
menu  lines    149,  265 
Menu  Manager   21,  47,  64,  71, 

146-155,  264 
MENU. PAS    419-421 
menus    10,  14,  21,  116,  146.  See 
also  specific  menu/menu 
command 
accepting  user  input    152-153 
appearance    148-149 
constructing    149-152 
custom    149 
disabling   116 
dividing  lines   148 
HodgePodge  and    31-33,  47 
modification  of   154-155 
organization  of  149 
MenuSelect    115 
menu  selections,  handling    153 
MenuShutDown  58 
MenuStartUp  45 
menu  title    146,  153 
message  dialog  box    135 
message  (event-record  field)    70 
MIDI  (Musical  Instrument  Digital 

Interface)  178 
mini-palettes  7,  99 
Miscellaneous  Tool  Set   20,  22,  42, 

181-182,  248 
missing  characters/symbol    95 
MMStartUp  43 
ModalDialog  141,  144 
modal  dialog  boxes    133,  139 
modeless  dialog  boxes    133,  136 
modes  (program)    12,  133 
modifier  key   71 

modifiers  (event-record  field)  70, 
71 
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Monitor  program   267 

debugging  with    247-248 
MountBootDisk    45,  307-308 
mouse    8,  10 
clicks    14,  15,  48 
double-clicks   71 
slot  for   9 
mouse-down  events    15,  16,  69,  71, 

73,  129 
mouseDownEvt   69 
mouse  routines  (Miscellaneous  Tool 

Set)    182 
mouse-up  events    69,  71 
mouseUpEvt   69 
movable  (memory-block  attribute) 

188 
MoveTo    43,  94,  106,  143 
MTShutDown  58 
MTStartUp  43 
multiple-language  programs, 

debugging    252-253 
multiple-segment  programming 

examples     241-245 
Munger  routine  (Miscellaneous  Tool 

Set)     182 
Musical  Instrument  Digital  Interface 
(MIDI)    178 


N 

native  mode    4,  173,  271-272,  274, 

291 
NDA.  See  new  desk  accessory 
new  desk  accessory  (NDA)    156, 
263,  289,  300.  See  also  classic 
desk  accessory;  desk 
accessories 
programming  examples    265 
supporting    157-158,  161 
writing    264-265 
NewDItem    134,  143 
NewHandle    41,  43,  122,  192,  211 
NEWLINE    211 
NewMenu   47,  149 
NewModalDialog  142,  143 
NewWindow   109,  124 
NewWindow  parameter  list  109, 

121,  123 
NIL     190 
Note  Alert    135 


Note  Sequencer    22,  177-178 
Note  Synthesizer    22,  177.  See  also 

sound/sound  hardware 
notXOR  mode    87 
null  event   69,  73 
nullEvt    69 
null  prefix   209 
numeric  keypad   8 


object  files    26,  226-229 
object  module  format  xviii,  26, 

198,  226,  257,  296 
object  segments    230-231 
offset  (into  color  table)   99 
OK  button    132,  133,  139 
OMF.  See  object  module  format 
OPEN    210,  211,  213 
Open  command  (File  menu)   32 
OpenFilter    162,  164,  218,  306 
opening  files    162,  210 
OpenNDA    158 
OpenPort   97 
open  routine  (NDA)   265 
OpenWindow    55,  120,  121,  163, 

305 
operating-environment  tool  sets 

22,   180-183 
operating  systems    xix 
calls  (typographic  convention  for) 
xxii 
origin 
of  character  93 
of  QuickDraw  II  coordinate  plane 

77 
of  rectangle    82 
oscillators  (sound)    175-176 
ovals  (QuickDraw  II)  87,  90 
overlays    233 


PackBytes  routine  (Miscellaneous 

Tool  Set)    182 
page-aligned  (memory-block 

attribute)    187 
page-down  region  (scroll  bar  part) 

126 
page  settings,  printing    167-168 


Page  Setup  command  (File  menu) 

32 
page-up  region  (scroll  bar  part)   126 
Paint    52-53 

painting  (QuickDraw  II)  87,  91 
Paint  It    52-53,  104,  170 
PAINT. PAS    439-442 
palettes   7,  99-100.  See  also  color 
palette;  color  tables 
standard  (640  mode)    102 
standard  (320  mode)    100 
parameter  lists  (ProDOS  16)    214 
parameter-passing    253    225 
ParamText     14 1 
part  code    127 
partial  pathname   208 
parts,  standard  window  110 
Pascal    65,  202,  225 

HodgePodge  and    36,  413-446 
Pascal  string   92 
Paste  command  (Edit  menu)    32, 

141,  159,  161 
patching   24,  227 
pathnames    196,  208,  288 

pointer  (QUIT)   202 
Pathname  segment    196 
pathname  table    196 
pattern 
Note  Sequencer    178 
QuickDraw  II  85 
pen    85 

pen  location   84,  85,  92 
pen  mode   86,  173 
pen  pattern    85 
pen  size   85 
permanent  initialization  files   266, 

300 
phrase  (Note  Sequencer)    178 
picture  files,  HodgePodge  and 

215-217,   218 
picture  (QuickDraw  II)  92 
picture  windows,  HodgePodge  and 
33,  52-53,  103-104,  305-306 
pixel  images    76,  103-104,  112, 
171,  286 
defined   79 
pixels    77,  79 
background  93 
defined    7 
foreground   93 
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relation  to  coordinate  plane 

locations  78 
shape  of  77,  90,  284 
plain-styled  characters  95 
plane  (window)  113,  136 
PMShutDown  58 
PMStartUp   46 
pointers    189-190 
pointing  devices    10,  71 
point  (QuickDraw  II)  88-89 
point  (typesetting)    95 
polygon  (QuickDraw  II)  87,  96 
port  (printer)    166 
port  (QuickDraw  II).  See  graphic 

ports;  GrafPort 
port  rectangle    81-82,  83,  103,  108 

120 
portSCB    80 
position-independent 

code/segments    188,  195,  196, 
197 
PPToPort    103,  104,  118 
PrChooser    167 
PrCloseDoc    170,  172 
PrClosePage    170,  172 
PrDefault   41 
prefixes    208-210,  288 

initial  values  210 
prefix  numbers    208-209 
PRINT. ASM    367-370 
print. cc   409-410 
Print  command  (File  menu)    32 
printing    166-173 

background  procedure    173 
choosing  a  printer    166-167 
draft    171 
errors    172 
GrafPort    170 

page  settings,  making    167-168 
printing  loop   172 
QuickDraw  II  and   170,  172,  173 
spool    172 
printing  loop   172 
Print  Manager    21,  64,  76,  166-173 

289 
print. pas   437-438 
print  records    171 
private  scrap    161 
PrJobDialog    170 
ProDOS  8   xix,  9,  207,  257,  290 


global  page   292,  296 
ProDOS  16  compared  to   291, 

296 
ProDOS  16  QUIT  call  and  202 
ProDOS  file  system    xix,  207-218 
ProDOS  16   xix,  10,  199,  200-202, 
257-259,  260 
compared  to  Macintosh  file 

system     287-288 
compared  to  ProDOS  8    291,  296 
direct-page/stack  segment, 

default    206 
Exerciser    253-254 
interrupt  handling    271-272 
parameter  lists    214 
prefixes    208-210 
QUIT  call   58,  202 
shell  applications  and  262 
Program  Bank  register    293 
program  descriptions  (APW) 

221-224 
program  launcher  201 
programming  examples.  See  also 
HodgePodge  or  specific 
routine 
assembly  language    190,  193, 

239-246,  263,  265,  311-376 
C    190,  377-412 
classic  desk  accessory   263 
dynamic-segment    245 
multiple-segment    241-245 
new  desk  accessory   265 
single-segment    240-241 
programming  techniques 

absolute  vs.  relocatable  segments 

24,  227 
applications   26,  228-229, 

256-259 
assembly  language    4,  283-284, 

290 
auxID  field    193 
controlling  programs   259-260 
control-related  events    129 
cutting  and  pasting    l60-l6l 
desk  accessories    262-265 
desktop    10 
dialogs  and  alerts   141 
Edit  menu    l6l 
error  testing    277 
event-driven    13-16,  51 


event  handling   70 
file  types    255-274 
general   xvii,  11,  277 
high-level  languages    282-283, 

290 
HodgePodge,  using    34-36,  276 
hybrid  applications   292-293 
initialization  files  266 
interactive    13,  14 
interrupt  handlers    270,  271-272 
language  considerations   225 
loading  programs   199 
loading  segments    198 
load-segment  characteristics    232 
Macintosh  program  conversions 

282-289 
math  computing    178-180 
memory  allocation    191-194 
menu  modification    154-155 
menu  organization   149 
object  module  format  and   26 
parameter-passing    225 
Print  Manager    171-173 
restartability  and  C   259 
segmentation    23-25,  219-254 
shell  applications   261-262 
standard  Apple  II  program 
enhancement    290-297 
static  vs.  dynamic  segments    25, 

232-235 
System  Loader    195 
TaskMaster  and   75 
tool  sets    18,  62,  272-274 
window  drawing  103-106, 

115-116 
window  origin,  resetting   120 
window-related  events    113-120 
program  selector    201 
PrOpenDoc    170,  172 
PrOpenPage    170,  172 
PrPicFile    170,  172 
PrStlDialog    169 
ptrToPixImage    80 
pull-down  menus.  See  menus 
purgeable  memory  blocks    194, 

233 
purge  level    187,  195 
purging    190,  194,  195,  197,  200 
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QDAuxShutDown  58 
QDAuxStartUp  45 
QDShutDown  58 
QDStartUp  43 
QuickDraw  (Macintosh)  136 
286-287 
relation  to  QuickDraw  II   75,  77, 
79,  286-287 
QuickDraw  II    20,  42,  63,  75-106, 
170.  See  also  specific  topic 
black  and  white  drawing  103 
color    98-103 
coordinates   77,  82 
how  it  draws  85-88 
limits  to  drawing  77 
Macintosh  QuickDraw,  relation  to 

75,  77,  79,  286-287 
pattern    85 

printing  and    170,  172,  173 
text  drawing    92-97 
what  it  draws  88-92 
where  it  draws   76-84 
QuickDraw  II  Auxiliary  20,  75 
QUIT    58,  199,  200-202,  260, 
261-262 
flag  word   202 
in  high-level  languages   201 
pathname  pointer    202 
Quit  command  (File  menu)   32,  58 
quit  return  stack    201 


radio  buttons    125,  128 

RAM   6,  9,  18.  See  also  memory 

RAM-based  tool  sets   43,  63 

RAM  expansion   5 

RAM  patches  (tool  sets)   43,  293 

READ    211 

reading  files    211-214 

rectangles  (QuickDraw  II)  87,  89 

data  structure   90 

origin  of  82 
reentrant  code    182 
RefreshDesktop    45 
regions  (QuickDraw  II)  87,  91 

defined    112 
registers    4,  66,  283 


RELOAD  segments    200,  207,  259 
relocatable  code   23,  24,  196,  197, 

226-227,  291,  295 
relocation  dictionary   228 
required  tool  sets    62-63 
resources  (Macintosh)   285 
Restart    200 
restartability,  C  and   259 
restartable    197,  200,  259 
restart-from-memory  flag  (QUIT) 

202 
restarting  programs  in  memory 

199-200 
return  flag  (QUIT)   202 
RGB  video    2,  7 
right  scroll  bar    110,  111 
ROM   9,  18.  See  also  memory 
ROM  expansion  5 
rounded-corner  rectangle 

(QuickDraw  II)  87,  90 
routines  (HodgePodge)    35,  59-60, 

303-304.  See  also  specific 

routine 
routines  (tool  set)    17.  See  also 

specific  routine 
how  to  call   65-67 
routine  numbers    66,  274 
total  number  of   62 
RTI     269 
RTL    260,  261,  262,  265 


sample  programs,  See  also 

HodgePodge;  programming 

examples 
SANE  (Standard  Apple  Numeric 

Environment)    xix-xx 
Save  As  command  (File  menu)   32 
Save  command  (File  menu)    50 
SaveOne    164,  165,  213 
saving  files    164 
scaled  fonts    287 

defined   96 
scan-line  control  byte   80,  100 
Scheduler    22,  182-183 
Scrap  Manager  21,  64,  158, 

159-161,  264 
ScrapShutDown   58 
ScrapStartUp  46 


screen  memory    76,  79 

scroll  bars   72,  110,  112,  117,  126, 

129    288,  289 
scrolling    73,  112,  117-120 
ScrollRect    117,  118 
Search  utility  (APW)   224 
segmentation    23-25,  228, 
230-238,  284     219-254 
absolute    24 
direct-page/stack    204 
dynamic    25,  195 
maximum  segment  size    23 
object    230-231 
relocatable   24 
static    25,  195 
segmented  programs,  debugging 

249 
SelectWindow   114 
self-booting  applications    257-258 

257-258 
sequence  (Note  Sequencer)    177 
serial  ports   2,  8,  9.  See  also  I/O 
SetBackColor    43,  94,  143 
SetCtlParams     127 
SetDAFont     141 
SET_EOF     214 
SET_FILE_INFO      214 
SetFontFlags     105 
SetForeColor    43,  94,  143 
SET.LEVEL      211 
SET_MARK     214 
SetMenuFlag    154,  155 
SetMItem     165 
SetMItemID     155 
SetMTitleStart    47 
SetOriginMask    124 
SetPenMode    17 
SetPenSize     17 
SetPort    97,  124,  134,  143 
SET_PREFIX      209 
SetRect    39,  40,  41,  104,  122,  123, 

134 
SetTextFace     143 
SetUpDef  ault   35,  41,  168 
SetUpMenus   35,  36,  47,  158 
SetUpWindows    35,41,123 
SetWTitle    165 
SFAllCaps    45 
SFGetFile    162,  163 
SFPutFile     164,  165 
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SFShutDown    58 

SFStartUp    45 

shadowed  rectangle    148 

shape  of  pixels   77,  90,  284 

Shaston    95 

shell    197 

shell  applications   241,  256,  259, 

261-262 
Shell  (APW)    199,  221-222,  259, 

261 
shell  identifier    26l 
ShowCursor   44 
ShowFont    53,  97,  105,  170 
ShowPleaseWait    46,  116,  134, 

142 
ShutDownTools   35, 58,  158 
shutting  down    197,  199-200 

HodgePodge    57,  58-59 
single-segment,  programming 

examples    240-241 
640  mode    7,  80,  98,  99    102 
65816  microprocessor   xiv,  3-5,  10, 

65,  291 
6502  microprocessor  xxi,  3,  9, 

294-295 
size  box    110,  111,  U2,  114 
size  of  coordinate  plane  77 
SizeWindow  114 

slots   2,  6,  8-9,  166.  See  also  I/O 
for  80-column  text  display  8 
for  mouse   9 
SmartPort,  slot  for   9 
smoothing    167 
Software  Licensing    279 
SOS    215-217 
Sound  GLU   8,  175 
sound/sound  hardware  2,  8,  9,  22, 
135,  174-176.  See  also  Note 
Synthesizer 
Sound  Tool  Set    22,  176 
source  files    26,  226-229 
assigning  load  segments  in 
234-236 
specialized  tool  sets   22 
special  memory    187 
spool  printing   172 
suck    4,  203,  269,  284,  293,  296 
stack  overflow    207 
stack  pointer    203,  262,  269,  294 
stack  underflow   207 


Standard  Apple  Numeric 

Environment  (SANE)    xix-xx 
Standard  Apple  Numeric 

Environment  Tool  Set    22, 
179-180 
standard  Apple  II    4,  10,  203,  290 
compatibility  of  Apple  IIGS  with 

9-10,  291-292 
defined  xxi 

program  enhancement    290-297 
Standard  File  Operations  Tool  Set 

21,  64,  162-165,  288,  289 
standard  linker  (APW)  223,  235, 

238 
standard  window  parts   1 10 
START    257,  258 
starting  up 
HodgePodge    38-47,  64 
tool  sets    38-41,  42-46,  62-67 
startupTools  35,  36,  42,  158, 

188 
static  segments    25,  195,  196,  200, 

232-235 
static  text    140,  14 1 
step  mode  (Note  Sequencer)    178 
StopAlert    309 
Stop  Alert    135 
structure  region    112 
Style  dialog  box    167 
styled  variations  (fonts)   34,  95,  96 
subroutines    230 

HodgePodge    35,  59-60, 
303-304 
Super  Hi-Res   xviii,  2,  6-7,  98,  284 
available  colors  7,  98 
color  palettes  7 
640  mode    7,  99,  102 
320  mode    7,  99,  101 
switch  events   68,  69,  73 
switchEvt   69 
switching  execution    199 
symbolic  reference    226,  238 
synthesizer.  See  Note  Synthesizer; 

sound/sound  hardware 
SysBeep  routine  (Miscellaneous 

Tool  Set)    182 
SysFailMgr    307 
SystemClick    158 
system  clock    9 
system  disk    298-301 


application   300-301 

complete     298-300 
SystemEdit     158 
system  event  mask    70 
System  Failure  Manager    176,  181 
system  file  levels    201,  211 
system  library  prefix    209 
System  Loader    22,  23,  180, 
195-200,  259 

loading  applications  198 

loading  relocatable  segments 
197 

types  of  load  segments    196 
system  menu  bar    147 
system  program  (ProDOS  8)    257 
system. SETUP/  subdirectory  300 
system  windows    111 


task  codes    48,  70,  74 

taskData  field  54,  153 

task  mask    74 

TaskMaster    48,  50,  51-53,  73-75, 
113-117,   152 
compared  to  GetNextEvent    68 
in  converting  Macintosh  programs 

286 
desk  accessories  and    158 
extended  task  event  record    74 
frame  controls  and    129,  130 
HodgePodge  and    51-53,  75, 

286 

menu-selection  handling    153 

programming  techniques  and   75 

scroll  bars  and    117 

window-related  events  and    115 
templates    140,  285 
temporary  initialization  files  266, 

300 
termination  character  (menu  and 

item  lines)    150 
text    92-97,  104-106 
text  block    92 
text  document    112 
text  mode    92 
text  strings    285 
Text  Tool  Set    21,  173,  261 
320  mode    7,  80,  98,  99,  147    100 
thumb  (scroll  bar  part)    126,  129 
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title  bar    110,  111,  114 

title  character  (menu  and  item  lines) 

150 
TLMountVolume    307,  308 
TLStartUp    43 

toolbox-defined  constants   38,  50 
toolbox-defined  data  structures   38 
Toolbox.  See  Apple  IIGS  Toolbox 
tool  initialization   134 
Tool  Locator    18,  20,  42,  62,  65-66, 

272-273 
tool  numbers    273 
tool  sets    17-22,  291.  See  also 

Apple  IIGS  Toolbox  or  specific 
tool  set 
advantages  of  using    18 
basic   20 

categories  of    19-22 
defined    17 

desktop-interface    20-21 
device-interface    21 
direct-page  space  for  42 
function  numbers   66,  274 
independence  from  operating 

system     18 
loading  63 
math    22 
number  of   62 
numbers    66,  273 
operating-environment    22 
programming  techniques    18,  62, 

272-274 
RAM-based   43,  63 
RAM  patches   43,  293 
required    62-63 
sound    22 
specialized   22 
starting  up    38-41,  42-46,  62-67 

62-67 
user-written    272-274 
version  number   63 
where  stored  on  disk   63 

TOOL. SETUP    300 
tool  table   42,  63 
TrackControl    71,  129 
TrackGoAway    114,  115 
tracking    153 
TrackZoom    114 
translation   277 
trigger  value    251 


typelD    192 
types    36 

U 

underlining  96 

Undo  command  (Edit  menu)   32, 

277 
unhighlighting   72,  153 
unloading    197,  198,  233,  246 
unlocking  handles    194,  277 
unpurgeable    195 
up  arrow  (scroll  bar  part)  126 
update  events    68,  69,  72,  115,  118 
updateEvt    69 
update  region    115,  117 
update  routine,  HodgePodge  and 

116 
updating   72,  73 
user-defined  constants    36 
User  ID    192-194,  201,  202,  241, 

247,  261 
User  ID  Manager   182,  192 
user  interrupt  vector    268,  270 
User  Shutdown    199,  200,  260 
user  tool  sets    256,  272-274 
user-written  tool  sets    272-274 
utilities  (APW)   223 


value  controls    125,  128,  130 
variable  initialization  (HodgePodge) 

38-41 
vector  routines    181 
versions    301 

of  HodgePodge    35 

of  tool  sets   63 
video  display   2,  6-7.  See  also 
Super  Hi-Res 

Double  Hi-Res   7 

80-column  text   6,  8,  260 

Hi-Res    7 
visible  region   81,  82,  84,  115 
visRgn    82 
volume  name    208 


W 

WaitCursor  46,  165,  170,  211 


wContDefProc    109 

wedges    91 

wFrame    109 

what  (event-record  field)   70 

when  (event-record  field)   70 

where  (event-record  field)   70 

width  (field  in  Loclnfo  record)   80 

wlnactMenu  75 

wlnContent  74 

wlnDesk  74 

wlnDeskltem  75 

WINDOW. ASM    337-352 

window. cc   390-399 

window  content  definition 

procedures    5 1 
window  drawing,  programming 

techniques    103-106,  115-116 
window  events   51,  72 

HodgePodge  and    56-57,  72 
window  frame    109,  111 
window  list  154 
Window  Manager  20,  64,  71-73,  82, 

91,  108-124    288 
window  menu  bars   147 
window  origin,  resetting   120 
WINDOW. PAS    425-428 
window  records   109 
window-related  events 
programming  techniques 

113-120 
TaskMaster  and    115 
windows   10,  14,  51,  81,  82, 
108-124 
active    114,  115,  116 
alert    110,  111,  116,  136 
application  111 
basic  features    108-113 
controls  and    129 
custom    111 
default  properties    108 
definition  procedures   51 
dialog    116,  136 
document    110,  111 
drawing  contents  of    115-116 
frame  colors    111 
GrafPorts,  relation  to    108-109 
HodgePodge  and    57,  120-124 
inactive    115 

port  rectangle  origin    120 
scrolling    117-120 
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standard  parts    110 
system     111 
Windows  menu  32 

wlnDrag  74 

WindShutDown  58 

WindStartUp  45 

WindStatus  58 

wlnFrame   75 

wlnGoAway  74 

wlnGrow  74 

wlnlnfo  75 

wlnMenuBar  50,  54,  74,  153 

wlnSpecial  75 

wlnSysWindow  75 

wlnZoom  74 

wRefCon  109 

WRITE  211,  213 

writing  to  files    211-214 

X 

X  register    66,  261 

Y 

Y  register    261 


zero  page    203,  269,  293,  296 
zoom  box/area   48,  110,  111,  112, 

114 
ZoomWindow  114 
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Programmer's  Introduction  to  the  Apple  IIgs® 

The  Official  Publication  from  Apple  Computer,  Inc. 

The  Apple  IIgs®  personal  computer— with  its  high  speed,  expandable  memory, 
super-high-resolution  color  graphics,  and  extensive  Toolbox  of  programming 
routines— has  created  a  powerful  new  programming  environment.  Written  for 
programmers  and  software  developers,  Programmer's  Introduction  to  the  Apple  IIgs 
explains  essential  concepts  and  provides  tips  and  practical  advice  from  the  designers 
of  the  Apple  IIgs  Toolbox  and  die  new  ProDOS®  16  operating  system. 

To  illustrate  these  concepts,  Programmer 's  Introduction  to  the  Apple  IIgs  includes 
three  complete  versions  of  a  functioning  sample  program  called  HodgePodge— in 
65816  assembly  language,  C,  and  Pascal.  Using  HodgePodge  as  an  example,  the  book 
demonstrates: 

•  Event-driven  programming  techniques 

•  Programming  with  the  Apple®  Desktop  user  interface 

•  Effective  use  of  the  Apple  IIgs  Toolbox 

•  How  to  write  segmented,  relocatable  code  that  will  make  programs  run  more  efficiently 

•  File  handling 

•  Memory  management 

•  How  to  write  specialized  programs  such  as  shells  and  desk  accessories 

Appendices  include  complete  source  code  listings  of  HodgePodge  in  all  three 
languages,  as  well  as  hints  on  converting  Apple  Macintosh®  programs  and  earlier  Apple 
II  programs  for  the  Apple  IIgs. 

Programmer's  Introduction  to  the  Apple  IIgs  contains  a  3.5-inch  disk  that  includes  both 
source  code  and  executable  versions  of  HodgePodge. 
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